Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 405 lines (402 sloc) 12.789 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 c…
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 [
111 {
112 Interface.name = "VDI";
113 description = "Operations which operate on Virtual Disk Images";
f1add48 @djs55 Start adding type declarations
authored
114 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
115 methods = [
116 {
117 Method.name = "create";
118 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.";
119 inputs = [
120 sr;
121 vdi_info';
122 params;
123 ];
124 outputs = [
125 { Arg.name = "new_vdi";
126 ty = vdi_info;
127 description = "The created Virtual Disk Image";
128 }
129 ];
130 }; {
131 Method.name = "snapshot";
132 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
133 inputs = [
134 sr;
135 vdi;
136 vdi_info';
137 params;
138 ];
139 outputs = [
140 { Arg.name = "new_vdi";
141 ty = vdi_info;
142 description = "[snapshot task sr vdi vdi_info params] creates a new VDI which is a snapshot of [vdi] in [sr]";
143 }
144 ];
145 }; {
146 Method.name = "clone";
147 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
148 inputs = [
149 sr;
150 vdi;
151 vdi_info';
152 params;
153 ];
154 outputs = [
155 { Arg.name = "new_vdi";
156 ty = vdi_info;
157 description = "[clone task sr vdi vdi_info params] creates a new VDI which is a clone of [vdi] in [sr]";
158 }
159 ];
160 }; {
161 Method.name = "destroy";
162 description = "[destroy task sr vdi] removes [vdi] from [sr]";
163 inputs = [
164 sr;
165 vdi;
166 ];
167 outputs = [
168 ];
169 }; {
170 Method.name = "attach";
171 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";
172 inputs = [
173 { Arg.name = "dp";
174 ty = Type.(Basic String);
175 description = "DataPath to attach this VDI for";
176 };
177 sr;
178 vdi;
179 { Arg.name = "read_write";
180 ty = Type.(Basic Boolean);
181 description = "If true then the DataPath will be used read/write, false otherwise";
182 }
183 ];
184 outputs = [
ed0f6b3 @djs55 smapi: VDI.attach returns params and a xenstore_data now
authored
185 { Arg.name = "device";
186 ty = Type.(Struct(("params", Basic String, "blkback params key"), [
187 "xenstore_data", Dict(String, Basic String), "additional backend configuration for xenstore-data/"
188 ]));
189 description = "backend device configuration";
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
190 }
191 ];
192 }; {
193 Method.name = "activate";
194 description = "[activate task dp sr vdi] signals the desire to immediately use [vdi]. This client must have called [attach] on the [vdi] first.";
195 inputs = [
196 { Arg.name = "dp";
197 ty = Type.(Basic String);
198 description = "DataPath to attach this VDI for";
199 };
200 sr;
201 vdi;
202 ];
203 outputs = [
204 ];
205 }; {
206 Method.name = "deactivate";
207 description = "[deactivate task dp sr vdi] signals that this client has stopped reading (and writing) [vdi].";
208 inputs = [
209 { Arg.name = "dp";
210 ty = Type.(Basic String);
211 description = "DataPath to deactivate";
212 };
213 sr;
214 vdi;
215 ];
216 outputs = [
217 ];
218 }; {
219 Method.name = "detach";
220 description = "[detach task dp sr vdi] signals that this client no-longer needs the [params] to be valid.";
221 inputs = [
222 { Arg.name = "dp";
223 ty = Type.(Basic String);
224 description = "DataPath to detach";
225 };
226 sr;
227 vdi;
228 ];
229 outputs = [
230 ];
231 }; {
232 Method.name = "copy";
233 description = "[copy task sr vdi url sr2] copies the data from [vdi] into a remote system [url]'s [sr2]";
234 inputs = [
235 sr;
236 vdi;
237 { Arg.name = "url";
238 ty = Type.(Basic String);
239 description = "URL which identifies a remote system";
240 };
241 { sr with Arg.name = "dest" };
242 ];
243 outputs = [
244 { vdi with Arg.name = "new_vdi" }
245 ];
246 }; {
247 Method.name = "get_url";
248 description = "[get_url task sr vdi] returns a URL suitable for accessing disk data directly.";
249 inputs = [
250 sr;
251 vdi
252 ];
253 outputs = [
254 { Arg.name = "url";
255 ty = Type.(Basic String);
256 description = "URL which represents this VDI";
257 }
258 ];
259 }; {
260 Method.name = "get_by_name";
261 description = "[get_by_name task sr name] returns the vdi within [sr] with [name]";
262 inputs = [
263 sr;
264 { Arg.name = "name";
265 ty = Type.(Basic String);
266 description = "Name of the VDI to return";
267 };
268 ];
269 outputs = [
270 vdi
271 ];
272 }; {
273 Method.name = "set_content_id";
274 description = "[set_content_id task sr vdi content_id] tells the storage backend that a VDI has an updated [content_id]";
275 inputs = [
276 sr;
277 vdi;
278 { Arg.name = "content_id";
279 ty = Type.(Basic String);
280 description = "New value of the VDI content_id field";
281 }
282 ];
283 outputs = [
284 ];
285 }; {
286 Method.name = "compose";
287 description = "[compose task sr vdi1 vdi2] layers the updates from [vdi2] onto [vdi1], modifying [vdi2]";
288 inputs = [
289 sr;
290 { vdi with Arg.name = "vdi1" };
291 { vdi with Arg.name = "vdi2" };
292 ];
293 outputs = [
294 ];
295 }
296
297 ]
298 }; {
299 Interface.name = "SR";
300 description = "Operations which act on Storage Repositories";
f1add48 @djs55 Start adding type declarations
authored
301 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
302 methods = [
303 {
304 Method.name = "attach";
305 description = "[attach task sr]: attaches the SR";
306 inputs = [
307 sr;
308 { Arg.name = "device_config";
309 ty = Type.(Dict(String, Basic String));
310 description = "Host-local SR configuration (e.g. address information)";
311 };
312 ];
313 outputs = [
314 ];
315 }; {
316 Method.name = "detach";
317 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.";
318 inputs = [
319 sr;
320 ];
321 outputs = [
322 ];
323 }; {
324 Method.name = "destroy";
325 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.";
326 inputs = [
327 sr;
328 ];
329 outputs = [
330 ];
331 }; {
332 Method.name = "reset";
333 description = "[reset task sr]: declares that the SR has been completely reset, e.g. by rebooting the VM hosting the SR backend.";
334 inputs = [
335 sr;
336 ];
337 outputs = [
338 ];
339 }; {
340 Method.name = "scan";
341 description = "[scan task sr] returns a list of VDIs contained within an attached SR";
342 inputs = [
343 sr;
344 ];
345 outputs = [
44d5a0d @djs55 Update the SMAPIv2, remove Mirror for now
authored
346 {
347 Arg.name = "vdis";
348 ty = Type.(Array (Name "vdi_info"));
349 description = "List of all the visible VDIs in the SR";
350 }
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
351 ];
352 }
353 ]
354 }; {
355 Interface.name = "DP";
356 description = "Operations which act on DataPaths";
f1add48 @djs55 Start adding type declarations
authored
357 type_decls = [];
b4afb46 @djs55 Move the SMAPIv2 definition to its own file, making way for a xenops API
authored
358 methods = [
359 {
360 Method.name = "create";
361 description = "[create task id]: creates and returns a dp";
362 inputs = [
363 { Arg.name = "id";
364 ty = Type.(Basic String);
365 description = "Human-readable DataPath name, for logging and diagnostics";
366 }
367 ];
368 outputs = [
369 { Arg.name = "id";
370 ty = Type.(Basic String);
371 description = "Abstract DataPath identifier";
372 }
373 ];
374 }; {
375 Method.name = "destroy";
376 description = "[destroy task id]: frees any resources associated with [id] and destroys it. This will typically do any needed VDI.detach, VDI.deactivate cleanup.";
377 inputs = [
378 { Arg.name = "id";
379 ty = Type.(Basic String);
380 description = "Abstract DataPath identifier";
381 }; {
382 Arg.name = "allow_leak";
383 ty = Type.(Basic Boolean);
384 description = "If true then a failure will be logged but the call will not fail";
385 }
386 ];
387 outputs = [
388 ];
389 }; {
390 Method.name = "diagnostics";
391 description = "[diagnostics ()]: returns a printable set of diagnostic information, typically including lists of all registered datapaths and their allocated resources.";
392 inputs = [
393 ];
394 outputs = [
395 { Arg.name = "diagnostics";
396 ty = Type.(Basic String);
397 description = "A string containing loggable human-readable diagnostics information";
398 }
399 ];
400 }
401 ]
402 }
403 ]
404 }
Something went wrong with that request. Please try again.