Skip to content
Newer
Older
100644 513 lines (509 sloc) 15.7 KB
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
1 open Types
2
3 let api =
4 let vdi_info =
5 Type.(Struct(
44d5a0d Update the SMAPIv2, remove Mirror for now
David Scott authored May 18, 2012
6 ( "vdi", Name "vdi", "The unique id of this VDI" ),
7 [ "sr", Name "sr", "The SR containing this VDI";
8 "content_id", Name "content_id", "The unique id of the VDI contents. If two VDIs have the same content_id then they must have the same data inside";
9b2bac2 Add per-field descriptions on the struct definitions
David Scott authored Mar 5, 2012
9 "name_label", Basic String, "Human-readable name of the VDI";
10 "name_description", Basic String, "Human-readable description of the VDI";
11 "ty", Basic String, "Used by a toolstack to remember why a VDI was created";
12 "metadata_of_pool", Basic String, "In the special case of a pool metadata containing VDI, this is the pool reference";
13 "is_a_snapshot", Basic Boolean, "True if the VDI is a snapshot of another VDI";
14 "snapshot_time", Basic String, "If is_a_snapshot is true then this is the time the snapshot was created";
15 "snapshot_of", Basic String, "If is_a_snapshot is true then this is the VDI which was snapshotted";
16 "read_only", Basic Boolean, "If true then this VDI is stored on read-only media";
17 "virtual_size", Basic Int64, "Size of the VDI from the perspective of a VM (in bytes)";
18 "physical_utilisation", Basic Int64, "Amount of space currently being consumed on the physical storage media";
826505e fs: add support for non-persistent disks
David Scott authored May 28, 2012
19 "persistent", Basic Boolean, "If true then disk modifications are preserved over VM reboot and shutdown";
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
20 ]
21 )) in
22 let sr = {
23 Arg.name = "sr";
24 ty = Type.(Basic String);
25 description = "The Storage Repository to operate within";
26 } in
27 let vdi = {
28 Arg.name = "vdi";
29 ty = Type.(Basic String);
30 description = "The Virtual Disk Image to operate on";
31 } in
44d5a0d Update the SMAPIv2, remove Mirror for now
David Scott authored May 18, 2012
32 let attach_info =
33 Type.(Struct(
34 ( "params", Basic String, "The xenstore backend params key"),
35 [ "xenstore_data", Dict(String, Basic String), "Additional xenstore backend device keys" ]
36 )) in
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
37 let vdi_info' = {
38 Arg.name = "vdi_info";
4e77f09 Fix lookup of named types within an environment. Note all types are c…
David Scott authored Mar 5, 2012
39 (* ty = vdi_info; *)
40 ty = Type.Name "vdi_info";
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
41 description = "The Virtual Disk Image properties";
42 } in
43 let params = {
44 Arg.name = "params";
45 ty = Type.(Dict(String, Basic String));
46 description = "Additional key/value pairs";
47 } in
48 {
329da8c Rename services for uniformity
David Scott authored Mar 7, 2012
49 Interfaces.name = "storage";
7161ddd Generate a nice index.html
David Scott authored Mar 7, 2012
50 title = "Storage Manager";
318abf0 Auto-generate the navbar index
David Scott authored Mar 6, 2012
51 description = "The Storage Manager (SM) is responsible for all storage operations on an XCP host. It organises Virtual Disk Images (VDIs) into homogenous collections known as Storage Repositories (SRs) where each collection is stored in a specific format (e.g. .vhd files on NFS, raw LUN on a iSCSI/FC storage array). The Storage Manager API (SMAPI) provides a simple abstract interface which allows the toolstack to create, destroy, snapshot, clone, resize etc VDIs within SRs";
29a5730 smapiv2: add declarations for exceptions
David Scott authored May 22, 2012
52 exn_decls = [
53 {
54 TyDecl.name = "Sr_not_attached";
55 description = "An SR must be attached in order to access VDIs";
5003d42 smapiv2: update to match Sr_not_attached arity change in xen-api
David Scott authored May 23, 2012
56 ty = Type.(Basic String)
29a5730 smapiv2: add declarations for exceptions
David Scott authored May 22, 2012
57 }; {
58 TyDecl.name = "Vdi_does_not_exist";
59 description = "The specified VDI could not be found in the SR";
1e67712 smapiv2: update following Vdi_does_not_exist arity-change in xen-api
David Scott authored May 23, 2012
60 ty = Type.(Basic String)
29a5730 smapiv2: add declarations for exceptions
David Scott authored May 22, 2012
61 }; {
62 TyDecl.name = "Illegal_transition";
63 description = "The requested VDI state transition is invalid";
64 ty = Type.(Pair(Basic String, Basic String))
65 }; {
66 TyDecl.name = "Backend_error";
67 description = "A backend-specific error occurred";
68 ty = Type.(Pair(Basic String, Array (Basic String)));
69 }; {
70 TyDecl.name = "Unimplemented";
71 description = "The operation has not been implemented";
70f0cd8 Fix exception marshalling
David Scott authored May 23, 2012
72 ty = Type.(Basic String);
29a5730 smapiv2: add declarations for exceptions
David Scott authored May 22, 2012
73 }; {
74 TyDecl.name = "Does_not_exist";
75 description = "The object does not exist";
76 ty = Type.(Pair(Basic String, Basic String));
77 }; {
78 TyDecl.name = "Cancelled";
79 description = "The task has been asynchronously cancelled";
80 ty = Type.(Basic String);
81 }; {
82 TyDecl.name = "Redirect";
83 description = "The request should be resent to this address";
84 ty = Type.(Basic String);
85 }; {
86 TyDecl.name = "Sr_attached";
87 description = "The operation cannot be performed because the SR is still attached";
1e67712 smapiv2: update following Vdi_does_not_exist arity-change in xen-api
David Scott authored May 23, 2012
88 ty = Type.(Basic String)
29a5730 smapiv2: add declarations for exceptions
David Scott authored May 22, 2012
89 }
90 ];
44d5a0d Update the SMAPIv2, remove Mirror for now
David Scott authored May 18, 2012
91 type_decls = [
92 {
93 TyDecl.name = "vdi";
94 description = "Primary key for a Virtual Disk Image (e.g. path on a storage system)";
95 ty = Type.(Basic String);
96 }; {
97 TyDecl.name = "sr";
98 description = "Primary key for a Storage Repository (e.g. a UUID)";
99 ty = Type.(Basic String);
100 }; {
101 TyDecl.name = "content_id";
102 description = "Identifies the contents (i.e. bytes with) a VDI. Two VDIs with the same content_id must have the same content.";
103 ty = Type.(Basic String);
104 }; {
105 TyDecl.name = "vdi_info";
106 description = "All per-VDI properties";
107 ty = vdi_info
108 };
109 ];
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
110 interfaces =
111 [
66cc2d4 smapiv2: move "query" into the module "Query" for consistency with xe…
David Scott authored May 22, 2012
112 {
113 Interface.name = "Query";
114 description = "Discover properties of this implementation";
115 type_decls = [
116 {
117 TyDecl.name = "query_result";
118 description = "properties of this implementation";
1381e33 smapiv2: update query_result to match xen-api change
David Scott authored May 24, 2012
119 ty = Type.(Struct( ("driver", Basic String, "driver, used in the XenAPI as SR.type"), [
120 "name", Basic String, "short name";
121 "description", Basic String, "description";
66cc2d4 smapiv2: move "query" into the module "Query" for consistency with xe…
David Scott authored May 22, 2012
122 "vendor", Basic String, "entity which produced this implementation";
1381e33 smapiv2: update query_result to match xen-api change
David Scott authored May 24, 2012
123 "copyright", Basic String, "copyright";
66cc2d4 smapiv2: move "query" into the module "Query" for consistency with xe…
David Scott authored May 22, 2012
124 "version", Basic String, "version";
1381e33 smapiv2: update query_result to match xen-api change
David Scott authored May 24, 2012
125 "required_api_version", Basic String, "minimum required API version";
126 "features", Array (Basic String), "features supported by this plugin";
127 "configuration", Dict(String, Basic String), "key/description pairs describing required device_config parameters"
66cc2d4 smapiv2: move "query" into the module "Query" for consistency with xe…
David Scott authored May 22, 2012
128 ]))
129 }
130 ];
131 methods = [
132 {
133 Method.name = "query";
134 description = "Query the implementation and return its properties";
135 inputs = [];
136 outputs = [
137 {
138 Arg.name = "query_result";
139 ty = Type.Name "query_result";
140 description = "The properies of this implementation"
141 }
142 ]
143 }
144 ]
145 };
146
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
147 {
148 Interface.name = "VDI";
149 description = "Operations which operate on Virtual Disk Images";
f1add48 Start adding type declarations
David Scott authored Mar 1, 2012
150 type_decls = [];
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
151 methods = [
152 {
153 Method.name = "create";
154 description = "[create task sr vdi_info params] creates a new VDI in [sr] using [vdi_info]. Some fields in the [vdi_info] may be modified (e.g. rounded up), so the function returns the vdi_info which was used.";
155 inputs = [
156 sr;
157 vdi_info';
158 params;
159 ];
160 outputs = [
161 { Arg.name = "new_vdi";
162 ty = vdi_info;
163 description = "The created Virtual Disk Image";
164 }
165 ];
166 }; {
167 Method.name = "snapshot";
168 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
169 inputs = [
170 sr;
171 vdi;
172 vdi_info';
173 params;
174 ];
175 outputs = [
176 { Arg.name = "new_vdi";
177 ty = vdi_info;
178 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
179 }
180 ];
181 }; {
182 Method.name = "clone";
183 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
184 inputs = [
185 sr;
186 vdi;
187 vdi_info';
188 params;
189 ];
190 outputs = [
191 { Arg.name = "new_vdi";
192 ty = vdi_info;
193 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
194 }
195 ];
196 }; {
197 Method.name = "destroy";
198 description = "[destroy task sr vdi] removes [vdi] from [sr]";
199 inputs = [
200 sr;
201 vdi;
202 ];
203 outputs = [
204 ];
205 }; {
af6f2f7 smapiv2: add VDI.stat
David Scott authored May 29, 2012
206 Method.name = "stat";
207 description = "[stat task sr vdi] returns metadata associated with VDI [vdi] in SR [sr].";
208 inputs = [
209 sr;
210 vdi;
211 ];
212 outputs = [
213 { Arg.name = "vdi_info";
214 ty = vdi_info;
215 description = "VDI metadata";
216 }
217 ];
218 }; {
e4cb5eb smapiv2: declare VDI.set_persistent
David Scott authored May 29, 2012
219 Method.name = "set_persistent";
220 description = "[set_persistent task sr vdi persistent] configures whether a VDI's contents should be persisted across epochs";
221 inputs = [
222 sr;
223 vdi;
224 { Arg.name = "persistent";
225 ty = Type.(Basic Boolean);
226 description = "New value of the VDI persistent field";
227 }
228 ];
229 outputs = [
230 ];
231 }; {
826505e fs: add support for non-persistent disks
David Scott authored May 28, 2012
232 Method.name = "epoch_begin";
233 description = "[epoch_begin task sr vdi] signals that VDI is about to be connected to a fresh (started, rebooted) VM.";
234 inputs = [
235 sr;
236 vdi;
237 ];
238 outputs = [
239 ];
240 }; {
241 Method.name = "epoch_end";
242 description = "[epoch_end task sr vdi] signals that VDI is about to be disconnected from a shutting-down/rebooting VM.";
243 inputs = [
244 sr;
245 vdi;
246 ];
247 outputs = [
248 ];
249 }; {
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
250 Method.name = "attach";
251 description = "[attach task dp sr vdi read_write] returns the [params] for a given [vdi] in [sr] which can be written to if (but not necessarily only if) [read_write] is true";
252 inputs = [
253 { Arg.name = "dp";
254 ty = Type.(Basic String);
255 description = "DataPath to attach this VDI for";
256 };
257 sr;
258 vdi;
259 { Arg.name = "read_write";
260 ty = Type.(Basic Boolean);
261 description = "If true then the DataPath will be used read/write, false otherwise";
262 }
263 ];
264 outputs = [
ed0f6b3 smapi: VDI.attach returns params and a xenstore_data now
David Scott authored May 21, 2012
265 { Arg.name = "device";
266 ty = Type.(Struct(("params", Basic String, "blkback params key"), [
267 "xenstore_data", Dict(String, Basic String), "additional backend configuration for xenstore-data/"
268 ]));
269 description = "backend device configuration";
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
270 }
271 ];
272 }; {
273 Method.name = "activate";
274 description = "[activate task dp sr vdi] signals the desire to immediately use [vdi]. This client must have called [attach] on the [vdi] first.";
275 inputs = [
276 { Arg.name = "dp";
277 ty = Type.(Basic String);
278 description = "DataPath to attach this VDI for";
279 };
280 sr;
281 vdi;
282 ];
283 outputs = [
284 ];
285 }; {
286 Method.name = "deactivate";
287 description = "[deactivate task dp sr vdi] signals that this client has stopped reading (and writing) [vdi].";
288 inputs = [
289 { Arg.name = "dp";
290 ty = Type.(Basic String);
291 description = "DataPath to deactivate";
292 };
293 sr;
294 vdi;
295 ];
296 outputs = [
297 ];
298 }; {
299 Method.name = "detach";
300 description = "[detach task dp sr vdi] signals that this client no-longer needs the [params] to be valid.";
301 inputs = [
302 { Arg.name = "dp";
303 ty = Type.(Basic String);
304 description = "DataPath to detach";
305 };
306 sr;
307 vdi;
308 ];
309 outputs = [
310 ];
311 }; {
312 Method.name = "copy";
313 description = "[copy task sr vdi url sr2] copies the data from [vdi] into a remote system [url]'s [sr2]";
314 inputs = [
315 sr;
316 vdi;
317 { Arg.name = "url";
318 ty = Type.(Basic String);
319 description = "URL which identifies a remote system";
320 };
321 { sr with Arg.name = "dest" };
322 ];
323 outputs = [
324 { vdi with Arg.name = "new_vdi" }
325 ];
326 }; {
327 Method.name = "get_url";
328 description = "[get_url task sr vdi] returns a URL suitable for accessing disk data directly.";
329 inputs = [
330 sr;
331 vdi
332 ];
333 outputs = [
334 { Arg.name = "url";
335 ty = Type.(Basic String);
336 description = "URL which represents this VDI";
337 }
338 ];
339 }; {
340 Method.name = "get_by_name";
341 description = "[get_by_name task sr name] returns the vdi within [sr] with [name]";
342 inputs = [
343 sr;
344 { Arg.name = "name";
345 ty = Type.(Basic String);
346 description = "Name of the VDI to return";
347 };
348 ];
349 outputs = [
350 vdi
351 ];
352 }; {
353 Method.name = "set_content_id";
354 description = "[set_content_id task sr vdi content_id] tells the storage backend that a VDI has an updated [content_id]";
355 inputs = [
356 sr;
357 vdi;
358 { Arg.name = "content_id";
359 ty = Type.(Basic String);
360 description = "New value of the VDI content_id field";
361 }
362 ];
363 outputs = [
364 ];
365 }; {
366 Method.name = "compose";
367 description = "[compose task sr vdi1 vdi2] layers the updates from [vdi2] onto [vdi1], modifying [vdi2]";
368 inputs = [
369 sr;
370 { vdi with Arg.name = "vdi1" };
371 { vdi with Arg.name = "vdi2" };
372 ];
373 outputs = [
374 ];
375 }
376
377 ]
378 }; {
379 Interface.name = "SR";
380 description = "Operations which act on Storage Repositories";
f1add48 Start adding type declarations
David Scott authored Mar 1, 2012
381 type_decls = [];
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
382 methods = [
959d313 smapiv2: add SR.create
David Scott authored May 22, 2012
383 {
9531032 SMAPIv2: add SR.list
David Scott authored May 23, 2012
384 Method.name = "list";
385 description = "[list dbg]: returns a list of attached SRs";
386 inputs = [];
387 outputs = [
388 {
389 Arg.name = "srs";
390 ty = Type.(Array (Basic String));
391 description = "The attached SRs"
392 }
393 ]
394 };
395 {
959d313 smapiv2: add SR.create
David Scott authored May 22, 2012
396 Method.name = "create";
397 description = "[create task sr device_config physical_size]: creates a fresh SR";
398 inputs = [
399 sr;
400 { Arg.name = "device_config";
401 ty = Type.(Dict(String, Basic String));
402 description = "Host-local SR configuration (e.g. address information)";
403 };
404 { Arg.name = "physical_size";
405 ty = Type.(Basic Int64);
406 description = "Requested maximum size of the SR (bytes)"
407 }
408 ];
409 outputs = []
410 };
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
411 {
412 Method.name = "attach";
413 description = "[attach task sr]: attaches the SR";
414 inputs = [
415 sr;
416 { Arg.name = "device_config";
417 ty = Type.(Dict(String, Basic String));
418 description = "Host-local SR configuration (e.g. address information)";
419 };
420 ];
421 outputs = [
422 ];
423 }; {
424 Method.name = "detach";
425 description = "[detach task sr]: detaches the SR, first detaching and/or deactivating any active VDIs. This may fail with Sr_not_attached, or any error from VDI.detach or VDI.deactivate.";
426 inputs = [
427 sr;
428 ];
429 outputs = [
430 ];
431 }; {
432 Method.name = "destroy";
433 description = "[destroy sr]: destroys (i.e. makes unattachable and unprobeable) the [sr], first detaching and/or deactivating any active VDIs. This may fail with Sr_not_attached, or any error from VDI.detach or VDI.deactivate.";
434 inputs = [
435 sr;
436 ];
437 outputs = [
438 ];
439 }; {
440 Method.name = "reset";
441 description = "[reset task sr]: declares that the SR has been completely reset, e.g. by rebooting the VM hosting the SR backend.";
442 inputs = [
443 sr;
444 ];
445 outputs = [
446 ];
447 }; {
448 Method.name = "scan";
449 description = "[scan task sr] returns a list of VDIs contained within an attached SR";
450 inputs = [
451 sr;
452 ];
453 outputs = [
44d5a0d Update the SMAPIv2, remove Mirror for now
David Scott authored May 18, 2012
454 {
455 Arg.name = "vdis";
456 ty = Type.(Array (Name "vdi_info"));
457 description = "List of all the visible VDIs in the SR";
458 }
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
459 ];
460 }
461 ]
462 }; {
463 Interface.name = "DP";
464 description = "Operations which act on DataPaths";
f1add48 Start adding type declarations
David Scott authored Mar 1, 2012
465 type_decls = [];
b4afb46 Move the SMAPIv2 definition to its own file, making way for a xenops API
David Scott authored Mar 1, 2012
466 methods = [
467 {
468 Method.name = "create";
469 description = "[create task id]: creates and returns a dp";
470 inputs = [
471 { Arg.name = "id";
472 ty = Type.(Basic String);
473 description = "Human-readable DataPath name, for logging and diagnostics";
474 }
475 ];
476 outputs = [
477 { Arg.name = "id";
478 ty = Type.(Basic String);
479 description = "Abstract DataPath identifier";
480 }
481 ];
482 }; {
483 Method.name = "destroy";
484 description = "[destroy task id]: frees any resources associated with [id] and destroys it. This will typically do any needed VDI.detach, VDI.deactivate cleanup.";
485 inputs = [
486 { Arg.name = "id";
487 ty = Type.(Basic String);
488 description = "Abstract DataPath identifier";
489 }; {
490 Arg.name = "allow_leak";
491 ty = Type.(Basic Boolean);
492 description = "If true then a failure will be logged but the call will not fail";
493 }
494 ];
495 outputs = [
496 ];
497 }; {
498 Method.name = "diagnostics";
499 description = "[diagnostics ()]: returns a printable set of diagnostic information, typically including lists of all registered datapaths and their allocated resources.";
500 inputs = [
501 ];
502 outputs = [
503 { Arg.name = "diagnostics";
504 ty = Type.(Basic String);
505 description = "A string containing loggable human-readable diagnostics information";
506 }
507 ];
508 }
509 ]
510 }
511 ]
512 }
Something went wrong with that request. Please try again.