Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 503 lines (500 sloc) 15.662 kb
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
1 open Types
2
3 let api =
4 let vdi_info =
5 Type.(Struct(
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
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 @djs55 Add per-field descriptions on the struct definitions
authored
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 @djs55 fs: add support for non-persistent disks
authored
19 "persistent", Basic Boolean, "If true then disk modifications are preserved over VM reboot and shutdown";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
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 @djs55 Update the SMAPIv2, remove Mirror for now
authored
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 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
37 let vdi_info' = {
38 Arg.name = "vdi_info";
4e77f09 @djs55 Fix lookup of named types within an environment. Note all types are curr...
authored
39 (* ty = vdi_info; *)
40 ty = Type.Name "vdi_info";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
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 @djs55 Rename services for uniformity
authored
49 Interfaces.name = "storage";
7161ddd @djs55 Generate a nice index.html
authored
50 title = "Storage Manager";
318abf0 @djs55 Auto-generate the navbar index
authored
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 @djs55 smapiv2: add declarations for exceptions
authored
52 exn_decls = [
53 {
54 TyDecl.name = "Sr_not_attached";
55 description = "An SR must be attached in order to access VDIs";
5003d42 @djs55 smapiv2: update to match Sr_not_attached arity change in xen-api
authored
56 ty = Type.(Basic String)
29a5730 @djs55 smapiv2: add declarations for exceptions
authored
57 }; {
58 TyDecl.name = "Vdi_does_not_exist";
59 description = "The specified VDI could not be found in the SR";
1e67712 @djs55 smapiv2: update following Vdi_does_not_exist arity-change in xen-api
authored
60 ty = Type.(Basic String)
29a5730 @djs55 smapiv2: add declarations for exceptions
authored
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 @djs55 Fix exception marshalling
authored
72 ty = Type.(Basic String);
29a5730 @djs55 smapiv2: add declarations for exceptions
authored
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 @djs55 smapiv2: update following Vdi_does_not_exist arity-change in xen-api
authored
88 ty = Type.(Basic String)
29a5730 @djs55 smapiv2: add declarations for exceptions
authored
89 }
90 ];
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
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 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
110 interfaces =
111 [
66cc2d4 @djs55 smapiv2: move "query" into the module "Query" for consistency with xenop...
authored
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 @djs55 smapiv2: update query_result to match xen-api change
authored
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 @djs55 smapiv2: move "query" into the module "Query" for consistency with xenop...
authored
122 "vendor", Basic String, "entity which produced this implementation";
1381e33 @djs55 smapiv2: update query_result to match xen-api change
authored
123 "copyright", Basic String, "copyright";
66cc2d4 @djs55 smapiv2: move "query" into the module "Query" for consistency with xenop...
authored
124 "version", Basic String, "version";
1381e33 @djs55 smapiv2: update query_result to match xen-api change
authored
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 @djs55 smapiv2: move "query" into the module "Query" for consistency with xenop...
authored
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 ]
d6a0d40 @djs55 smapiv2: add Query.diagnostics
authored
143 }; {
144 Method.name = "diagnostics";
145 description = "[diagnostics ()]: returns a printable set of backend diagnostic information.";
146 inputs = [
147 ];
148 outputs = [
149 { Arg.name = "diagnostics";
150 ty = Type.(Basic String);
151 description = "A string containing loggable human-readable diagnostics information";
152 }
153 ];
66cc2d4 @djs55 smapiv2: move "query" into the module "Query" for consistency with xenop...
authored
154 }
155 ]
156 };
157
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
158 {
159 Interface.name = "VDI";
160 description = "Operations which operate on Virtual Disk Images";
f1add48 @djs55 Start adding type declarations
authored
161 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
162 methods = [
163 {
164 Method.name = "create";
165 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.";
166 inputs = [
167 sr;
168 vdi_info';
169 params;
170 ];
171 outputs = [
172 { Arg.name = "new_vdi";
173 ty = vdi_info;
174 description = "The created Virtual Disk Image";
175 }
176 ];
177 }; {
178 Method.name = "snapshot";
179 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
180 inputs = [
181 sr;
182 vdi;
183 vdi_info';
184 params;
185 ];
186 outputs = [
187 { Arg.name = "new_vdi";
188 ty = vdi_info;
189 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
190 }
191 ];
192 }; {
193 Method.name = "clone";
194 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
195 inputs = [
196 sr;
197 vdi;
198 vdi_info';
199 params;
200 ];
201 outputs = [
202 { Arg.name = "new_vdi";
203 ty = vdi_info;
204 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
205 }
206 ];
207 }; {
780a37c @djs55 smapiv2: declare VDI.snapshot
authored
208 Method.name = "snapshot";
209 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a readonly snapshot of [vdi] in [sr]";
210 inputs = [
211 sr;
212 vdi;
213 vdi_info';
214 params;
215 ];
216 outputs = [
217 { Arg.name = "new_vdi";
218 ty = vdi_info;
219 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
220 }
221 ];
222 }; {
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
223 Method.name = "destroy";
224 description = "[destroy task sr vdi] removes [vdi] from [sr]";
225 inputs = [
226 sr;
227 vdi;
228 ];
229 outputs = [
230 ];
231 }; {
af6f2f7 @djs55 smapiv2: add VDI.stat
authored
232 Method.name = "stat";
233 description = "[stat task sr vdi] returns metadata associated with VDI [vdi] in SR [sr].";
234 inputs = [
235 sr;
236 vdi;
237 ];
238 outputs = [
239 { Arg.name = "vdi_info";
240 ty = vdi_info;
241 description = "VDI metadata";
242 }
243 ];
244 }; {
e4cb5eb @djs55 smapiv2: declare VDI.set_persistent
authored
245 Method.name = "set_persistent";
246 description = "[set_persistent task sr vdi persistent] configures whether a VDI's contents should be persisted across epochs";
247 inputs = [
248 sr;
249 vdi;
250 { Arg.name = "persistent";
251 ty = Type.(Basic Boolean);
252 description = "New value of the VDI persistent field";
253 }
254 ];
255 outputs = [
256 ];
257 }; {
826505e @djs55 fs: add support for non-persistent disks
authored
258 Method.name = "epoch_begin";
259 description = "[epoch_begin task sr vdi] signals that VDI is about to be connected to a fresh (started, rebooted) VM.";
260 inputs = [
261 sr;
262 vdi;
263 ];
264 outputs = [
265 ];
266 }; {
267 Method.name = "epoch_end";
268 description = "[epoch_end task sr vdi] signals that VDI is about to be disconnected from a shutting-down/rebooting VM.";
269 inputs = [
270 sr;
271 vdi;
272 ];
273 outputs = [
274 ];
275 }; {
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
276 Method.name = "attach";
277 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";
278 inputs = [
279 { Arg.name = "dp";
280 ty = Type.(Basic String);
281 description = "DataPath to attach this VDI for";
282 };
283 sr;
284 vdi;
285 { Arg.name = "read_write";
286 ty = Type.(Basic Boolean);
287 description = "If true then the DataPath will be used read/write, false otherwise";
288 }
289 ];
290 outputs = [
ed0f6b3 @djs55 smapi: VDI.attach returns params and a xenstore_data now
authored
291 { Arg.name = "device";
292 ty = Type.(Struct(("params", Basic String, "blkback params key"), [
293 "xenstore_data", Dict(String, Basic String), "additional backend configuration for xenstore-data/"
294 ]));
295 description = "backend device configuration";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
296 }
297 ];
298 }; {
299 Method.name = "activate";
300 description = "[activate task dp sr vdi] signals the desire to immediately use [vdi]. This client must have called [attach] on the [vdi] first.";
301 inputs = [
302 { Arg.name = "dp";
303 ty = Type.(Basic String);
304 description = "DataPath to attach this VDI for";
305 };
306 sr;
307 vdi;
308 ];
309 outputs = [
310 ];
311 }; {
312 Method.name = "deactivate";
313 description = "[deactivate task dp sr vdi] signals that this client has stopped reading (and writing) [vdi].";
314 inputs = [
315 { Arg.name = "dp";
316 ty = Type.(Basic String);
317 description = "DataPath to deactivate";
318 };
319 sr;
320 vdi;
321 ];
322 outputs = [
323 ];
324 }; {
325 Method.name = "detach";
326 description = "[detach task dp sr vdi] signals that this client no-longer needs the [params] to be valid.";
327 inputs = [
328 { Arg.name = "dp";
329 ty = Type.(Basic String);
330 description = "DataPath to detach";
331 };
332 sr;
333 vdi;
334 ];
335 outputs = [
336 ];
337 }; {
338 Method.name = "copy";
339 description = "[copy task sr vdi url sr2] copies the data from [vdi] into a remote system [url]'s [sr2]";
340 inputs = [
341 sr;
342 vdi;
343 { Arg.name = "url";
344 ty = Type.(Basic String);
345 description = "URL which identifies a remote system";
346 };
347 { sr with Arg.name = "dest" };
348 ];
349 outputs = [
350 { vdi with Arg.name = "new_vdi" }
351 ];
352 }; {
353 Method.name = "get_url";
354 description = "[get_url task sr vdi] returns a URL suitable for accessing disk data directly.";
355 inputs = [
356 sr;
357 vdi
358 ];
359 outputs = [
360 { Arg.name = "url";
361 ty = Type.(Basic String);
362 description = "URL which represents this VDI";
363 }
364 ];
365 }; {
366 Method.name = "get_by_name";
367 description = "[get_by_name task sr name] returns the vdi within [sr] with [name]";
368 inputs = [
369 sr;
370 { Arg.name = "name";
371 ty = Type.(Basic String);
372 description = "Name of the VDI to return";
373 };
374 ];
375 outputs = [
376 vdi
377 ];
378 }; {
379 Method.name = "set_content_id";
380 description = "[set_content_id task sr vdi content_id] tells the storage backend that a VDI has an updated [content_id]";
381 inputs = [
382 sr;
383 vdi;
384 { Arg.name = "content_id";
385 ty = Type.(Basic String);
386 description = "New value of the VDI content_id field";
387 }
388 ];
389 outputs = [
390 ];
391 }; {
392 Method.name = "compose";
393 description = "[compose task sr vdi1 vdi2] layers the updates from [vdi2] onto [vdi1], modifying [vdi2]";
394 inputs = [
395 sr;
396 { vdi with Arg.name = "vdi1" };
397 { vdi with Arg.name = "vdi2" };
398 ];
399 outputs = [
400 ];
297139e @djs55 smapiv2: add VDI.get_by_name
authored
401 }; {
402 Method.name = "get_by_name";
403 description = "[get_by_name sr name] resolves a name to a VDI";
404 inputs = [
405 sr;
406 { Arg.name = "name";
407 ty = Type.(Basic String);
408 description = "Name of VDI to resolve"
409 }
410 ];
411 outputs = [
412 vdi
413 ]
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
414 }
415 ]
416 }; {
417 Interface.name = "SR";
418 description = "Operations which act on Storage Repositories";
f1add48 @djs55 Start adding type declarations
authored
419 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
420 methods = [
959d313 @djs55 smapiv2: add SR.create
authored
421 {
9531032 @djs55 SMAPIv2: add SR.list
authored
422 Method.name = "list";
423 description = "[list dbg]: returns a list of attached SRs";
424 inputs = [];
425 outputs = [
426 {
427 Arg.name = "srs";
428 ty = Type.(Array (Basic String));
429 description = "The attached SRs"
430 }
431 ]
432 };
433 {
959d313 @djs55 smapiv2: add SR.create
authored
434 Method.name = "create";
435 description = "[create task sr device_config physical_size]: creates a fresh SR";
436 inputs = [
437 sr;
438 { Arg.name = "device_config";
439 ty = Type.(Dict(String, Basic String));
440 description = "Host-local SR configuration (e.g. address information)";
441 };
442 { Arg.name = "physical_size";
443 ty = Type.(Basic Int64);
444 description = "Requested maximum size of the SR (bytes)"
445 }
446 ];
447 outputs = []
448 };
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
449 {
450 Method.name = "attach";
451 description = "[attach task sr]: attaches the SR";
452 inputs = [
453 sr;
454 { Arg.name = "device_config";
455 ty = Type.(Dict(String, Basic String));
456 description = "Host-local SR configuration (e.g. address information)";
457 };
458 ];
459 outputs = [
460 ];
461 }; {
462 Method.name = "detach";
463 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.";
464 inputs = [
465 sr;
466 ];
467 outputs = [
468 ];
469 }; {
470 Method.name = "destroy";
471 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.";
472 inputs = [
473 sr;
474 ];
475 outputs = [
476 ];
477 }; {
478 Method.name = "reset";
479 description = "[reset task sr]: declares that the SR has been completely reset, e.g. by rebooting the VM hosting the SR backend.";
480 inputs = [
481 sr;
482 ];
483 outputs = [
484 ];
485 }; {
486 Method.name = "scan";
487 description = "[scan task sr] returns a list of VDIs contained within an attached SR";
488 inputs = [
489 sr;
490 ];
491 outputs = [
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
492 {
493 Arg.name = "vdis";
494 ty = Type.(Array (Name "vdi_info"));
495 description = "List of all the visible VDIs in the SR";
496 }
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
497 ];
498 }
499 ]
500 }
501 ]
502 }
Something went wrong with that request. Please try again.