Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 451 lines (447 sloc) 14.153 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";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
19 ]
20 )) in
21 let sr = {
22 Arg.name = "sr";
23 ty = Type.(Basic String);
24 description = "The Storage Repository to operate within";
25 } in
26 let vdi = {
27 Arg.name = "vdi";
28 ty = Type.(Basic String);
29 description = "The Virtual Disk Image to operate on";
30 } in
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
31 let attach_info =
32 Type.(Struct(
33 ( "params", Basic String, "The xenstore backend params key"),
34 [ "xenstore_data", Dict(String, Basic String), "Additional xenstore backend device keys" ]
35 )) in
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
36 let vdi_info' = {
37 Arg.name = "vdi_info";
4e77f09 @djs55 Fix lookup of named types within an environment. Note all types are curr...
authored
38 (* ty = vdi_info; *)
39 ty = Type.Name "vdi_info";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
40 description = "The Virtual Disk Image properties";
41 } in
42 let params = {
43 Arg.name = "params";
44 ty = Type.(Dict(String, Basic String));
45 description = "Additional key/value pairs";
46 } in
47 {
329da8c @djs55 Rename services for uniformity
authored
48 Interfaces.name = "storage";
7161ddd @djs55 Generate a nice index.html
authored
49 title = "Storage Manager";
318abf0 @djs55 Auto-generate the navbar index
authored
50 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
51 exn_decls = [
52 {
53 TyDecl.name = "Sr_not_attached";
54 description = "An SR must be attached in order to access VDIs";
55 ty = Type.Unit
56 }; {
57 TyDecl.name = "Vdi_does_not_exist";
58 description = "The specified VDI could not be found in the SR";
59 ty = Type.Unit
60 }; {
61 TyDecl.name = "Illegal_transition";
62 description = "The requested VDI state transition is invalid";
63 ty = Type.(Pair(Basic String, Basic String))
64 }; {
65 TyDecl.name = "Backend_error";
66 description = "A backend-specific error occurred";
67 ty = Type.(Pair(Basic String, Array (Basic String)));
68 }; {
69 TyDecl.name = "Unimplemented";
70 description = "The operation has not been implemented";
71 ty = Type.Unit;
72 }; {
73 TyDecl.name = "Does_not_exist";
74 description = "The object does not exist";
75 ty = Type.(Pair(Basic String, Basic String));
76 }; {
77 TyDecl.name = "Cancelled";
78 description = "The task has been asynchronously cancelled";
79 ty = Type.(Basic String);
80 }; {
81 TyDecl.name = "Redirect";
82 description = "The request should be resent to this address";
83 ty = Type.(Basic String);
84 }; {
85 TyDecl.name = "Sr_attached";
86 description = "The operation cannot be performed because the SR is still attached";
87 ty = Type.Unit
88 }
89 ];
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
90 type_decls = [
91 {
92 TyDecl.name = "vdi";
93 description = "Primary key for a Virtual Disk Image (e.g. path on a storage system)";
94 ty = Type.(Basic String);
95 }; {
96 TyDecl.name = "sr";
97 description = "Primary key for a Storage Repository (e.g. a UUID)";
98 ty = Type.(Basic String);
99 }; {
100 TyDecl.name = "content_id";
101 description = "Identifies the contents (i.e. bytes with) a VDI. Two VDIs with the same content_id must have the same content.";
102 ty = Type.(Basic String);
103 }; {
104 TyDecl.name = "vdi_info";
105 description = "All per-VDI properties";
106 ty = vdi_info
107 };
108 ];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
109 interfaces =
110 [
66cc2d4 @djs55 smapiv2: move "query" into the module "Query" for consistency with xenop...
authored
111 {
112 Interface.name = "Query";
113 description = "Discover properties of this implementation";
114 type_decls = [
115 {
116 TyDecl.name = "query_result";
117 description = "properties of this implementation";
118 ty = Type.(Struct( ("name", Basic String, "short name"), [
119 "vendor", Basic String, "entity which produced this implementation";
120 "version", Basic String, "version";
121 "features", Array (Basic String), "features supported by this plugin"
122 ]))
123 }
124 ];
125 methods = [
126 {
127 Method.name = "query";
128 description = "Query the implementation and return its properties";
129 inputs = [];
130 outputs = [
131 {
132 Arg.name = "query_result";
133 ty = Type.Name "query_result";
134 description = "The properies of this implementation"
135 }
136 ]
137 }
138 ]
139 };
140
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
141 {
142 Interface.name = "VDI";
143 description = "Operations which operate on Virtual Disk Images";
f1add48 @djs55 Start adding type declarations
authored
144 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
145 methods = [
146 {
147 Method.name = "create";
148 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.";
149 inputs = [
150 sr;
151 vdi_info';
152 params;
153 ];
154 outputs = [
155 { Arg.name = "new_vdi";
156 ty = vdi_info;
157 description = "The created Virtual Disk Image";
158 }
159 ];
160 }; {
161 Method.name = "snapshot";
162 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
163 inputs = [
164 sr;
165 vdi;
166 vdi_info';
167 params;
168 ];
169 outputs = [
170 { Arg.name = "new_vdi";
171 ty = vdi_info;
172 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
173 }
174 ];
175 }; {
176 Method.name = "clone";
177 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
178 inputs = [
179 sr;
180 vdi;
181 vdi_info';
182 params;
183 ];
184 outputs = [
185 { Arg.name = "new_vdi";
186 ty = vdi_info;
187 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
188 }
189 ];
190 }; {
191 Method.name = "destroy";
192 description = "[destroy task sr vdi] removes [vdi] from [sr]";
193 inputs = [
194 sr;
195 vdi;
196 ];
197 outputs = [
198 ];
199 }; {
200 Method.name = "attach";
201 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";
202 inputs = [
203 { Arg.name = "dp";
204 ty = Type.(Basic String);
205 description = "DataPath to attach this VDI for";
206 };
207 sr;
208 vdi;
209 { Arg.name = "read_write";
210 ty = Type.(Basic Boolean);
211 description = "If true then the DataPath will be used read/write, false otherwise";
212 }
213 ];
214 outputs = [
ed0f6b3 @djs55 smapi: VDI.attach returns params and a xenstore_data now
authored
215 { Arg.name = "device";
216 ty = Type.(Struct(("params", Basic String, "blkback params key"), [
217 "xenstore_data", Dict(String, Basic String), "additional backend configuration for xenstore-data/"
218 ]));
219 description = "backend device configuration";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
220 }
221 ];
222 }; {
223 Method.name = "activate";
224 description = "[activate task dp sr vdi] signals the desire to immediately use [vdi]. This client must have called [attach] on the [vdi] first.";
225 inputs = [
226 { Arg.name = "dp";
227 ty = Type.(Basic String);
228 description = "DataPath to attach this VDI for";
229 };
230 sr;
231 vdi;
232 ];
233 outputs = [
234 ];
235 }; {
236 Method.name = "deactivate";
237 description = "[deactivate task dp sr vdi] signals that this client has stopped reading (and writing) [vdi].";
238 inputs = [
239 { Arg.name = "dp";
240 ty = Type.(Basic String);
241 description = "DataPath to deactivate";
242 };
243 sr;
244 vdi;
245 ];
246 outputs = [
247 ];
248 }; {
249 Method.name = "detach";
250 description = "[detach task dp sr vdi] signals that this client no-longer needs the [params] to be valid.";
251 inputs = [
252 { Arg.name = "dp";
253 ty = Type.(Basic String);
254 description = "DataPath to detach";
255 };
256 sr;
257 vdi;
258 ];
259 outputs = [
260 ];
261 }; {
262 Method.name = "copy";
263 description = "[copy task sr vdi url sr2] copies the data from [vdi] into a remote system [url]'s [sr2]";
264 inputs = [
265 sr;
266 vdi;
267 { Arg.name = "url";
268 ty = Type.(Basic String);
269 description = "URL which identifies a remote system";
270 };
271 { sr with Arg.name = "dest" };
272 ];
273 outputs = [
274 { vdi with Arg.name = "new_vdi" }
275 ];
276 }; {
277 Method.name = "get_url";
278 description = "[get_url task sr vdi] returns a URL suitable for accessing disk data directly.";
279 inputs = [
280 sr;
281 vdi
282 ];
283 outputs = [
284 { Arg.name = "url";
285 ty = Type.(Basic String);
286 description = "URL which represents this VDI";
287 }
288 ];
289 }; {
290 Method.name = "get_by_name";
291 description = "[get_by_name task sr name] returns the vdi within [sr] with [name]";
292 inputs = [
293 sr;
294 { Arg.name = "name";
295 ty = Type.(Basic String);
296 description = "Name of the VDI to return";
297 };
298 ];
299 outputs = [
300 vdi
301 ];
302 }; {
303 Method.name = "set_content_id";
304 description = "[set_content_id task sr vdi content_id] tells the storage backend that a VDI has an updated [content_id]";
305 inputs = [
306 sr;
307 vdi;
308 { Arg.name = "content_id";
309 ty = Type.(Basic String);
310 description = "New value of the VDI content_id field";
311 }
312 ];
313 outputs = [
314 ];
315 }; {
316 Method.name = "compose";
317 description = "[compose task sr vdi1 vdi2] layers the updates from [vdi2] onto [vdi1], modifying [vdi2]";
318 inputs = [
319 sr;
320 { vdi with Arg.name = "vdi1" };
321 { vdi with Arg.name = "vdi2" };
322 ];
323 outputs = [
324 ];
325 }
326
327 ]
328 }; {
329 Interface.name = "SR";
330 description = "Operations which act on Storage Repositories";
f1add48 @djs55 Start adding type declarations
authored
331 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
332 methods = [
959d313 @djs55 smapiv2: add SR.create
authored
333 {
334 Method.name = "create";
335 description = "[create task sr device_config physical_size]: creates a fresh SR";
336 inputs = [
337 sr;
338 { Arg.name = "device_config";
339 ty = Type.(Dict(String, Basic String));
340 description = "Host-local SR configuration (e.g. address information)";
341 };
342 { Arg.name = "physical_size";
343 ty = Type.(Basic Int64);
344 description = "Requested maximum size of the SR (bytes)"
345 }
346 ];
347 outputs = []
348 };
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
349 {
350 Method.name = "attach";
351 description = "[attach task sr]: attaches the SR";
352 inputs = [
353 sr;
354 { Arg.name = "device_config";
355 ty = Type.(Dict(String, Basic String));
356 description = "Host-local SR configuration (e.g. address information)";
357 };
358 ];
359 outputs = [
360 ];
361 }; {
362 Method.name = "detach";
363 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.";
364 inputs = [
365 sr;
366 ];
367 outputs = [
368 ];
369 }; {
370 Method.name = "destroy";
371 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.";
372 inputs = [
373 sr;
374 ];
375 outputs = [
376 ];
377 }; {
378 Method.name = "reset";
379 description = "[reset task sr]: declares that the SR has been completely reset, e.g. by rebooting the VM hosting the SR backend.";
380 inputs = [
381 sr;
382 ];
383 outputs = [
384 ];
385 }; {
386 Method.name = "scan";
387 description = "[scan task sr] returns a list of VDIs contained within an attached SR";
388 inputs = [
389 sr;
390 ];
391 outputs = [
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
392 {
393 Arg.name = "vdis";
394 ty = Type.(Array (Name "vdi_info"));
395 description = "List of all the visible VDIs in the SR";
396 }
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
397 ];
398 }
399 ]
400 }; {
401 Interface.name = "DP";
402 description = "Operations which act on DataPaths";
f1add48 @djs55 Start adding type declarations
authored
403 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
404 methods = [
405 {
406 Method.name = "create";
407 description = "[create task id]: creates and returns a dp";
408 inputs = [
409 { Arg.name = "id";
410 ty = Type.(Basic String);
411 description = "Human-readable DataPath name, for logging and diagnostics";
412 }
413 ];
414 outputs = [
415 { Arg.name = "id";
416 ty = Type.(Basic String);
417 description = "Abstract DataPath identifier";
418 }
419 ];
420 }; {
421 Method.name = "destroy";
422 description = "[destroy task id]: frees any resources associated with [id] and destroys it. This will typically do any needed VDI.detach, VDI.deactivate cleanup.";
423 inputs = [
424 { Arg.name = "id";
425 ty = Type.(Basic String);
426 description = "Abstract DataPath identifier";
427 }; {
428 Arg.name = "allow_leak";
429 ty = Type.(Basic Boolean);
430 description = "If true then a failure will be logged but the call will not fail";
431 }
432 ];
433 outputs = [
434 ];
435 }; {
436 Method.name = "diagnostics";
437 description = "[diagnostics ()]: returns a printable set of diagnostic information, typically including lists of all registered datapaths and their allocated resources.";
438 inputs = [
439 ];
440 outputs = [
441 { Arg.name = "diagnostics";
442 ty = Type.(Basic String);
443 description = "A string containing loggable human-readable diagnostics information";
444 }
445 ];
446 }
447 ]
448 }
449 ]
450 }
Something went wrong with that request. Please try again.