]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright (c) Intel Corporation. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | /** \file | |
35 | * Blob Storage System | |
36 | * | |
37 | * The blob storage system, or the blobstore for short, is a low level | |
38 | * library for placing opaque blobs of data onto a storage device such | |
39 | * that scattered physical blocks on the storage device appear as a | |
40 | * single, contiguous storage region. These blobs are also persistent, | |
41 | * which means they are rediscoverable after reboot or power loss. | |
42 | * | |
43 | * The blobstore is designed to be very high performance, and thus has | |
44 | * a few general rules regarding thread safety to avoid taking locks | |
11fdf7f2 TL |
45 | * in the I/O path. This is primarily done by only allowing most |
46 | * functions to be called on the metadata thread. The metadata thread is | |
47 | * the thread which called spdk_bs_init() or spdk_bs_load(). | |
7c673cae | 48 | * |
11fdf7f2 TL |
49 | * Functions starting with the prefix "spdk_blob_io" are passed a channel |
50 | * as an argument, and channels may only be used from the thread they were | |
51 | * created on. See \ref spdk_bs_alloc_io_channel. These are the only | |
52 | * functions that may be called from a thread other than the metadata | |
53 | * thread. | |
7c673cae | 54 | * |
11fdf7f2 | 55 | * The blobstore returns errors using negated POSIX errno values, either |
7c673cae FG |
56 | * returned in the callback or as a return value. An errno value of 0 means |
57 | * success. | |
58 | */ | |
59 | ||
60 | #ifndef SPDK_BLOB_H | |
61 | #define SPDK_BLOB_H | |
62 | ||
11fdf7f2 TL |
63 | #include "spdk/stdinc.h" |
64 | ||
65 | #ifdef __cplusplus | |
66 | extern "C" { | |
67 | #endif | |
7c673cae FG |
68 | |
69 | typedef uint64_t spdk_blob_id; | |
70 | #define SPDK_BLOBID_INVALID (uint64_t)-1 | |
11fdf7f2 | 71 | #define SPDK_BLOBSTORE_TYPE_LENGTH 16 |
7c673cae FG |
72 | |
73 | struct spdk_blob_store; | |
74 | struct spdk_io_channel; | |
75 | struct spdk_blob; | |
76 | struct spdk_xattr_names; | |
77 | ||
11fdf7f2 TL |
78 | /** |
79 | * Blobstore operation completion callback. | |
80 | * | |
81 | * \param cb_arg Callback argument. | |
82 | * \param bserrno 0 if it completed successfully, or negative errno if it failed. | |
83 | */ | |
7c673cae | 84 | typedef void (*spdk_bs_op_complete)(void *cb_arg, int bserrno); |
11fdf7f2 TL |
85 | |
86 | /** | |
87 | * Blobstore operation completion callback with handle. | |
88 | * | |
89 | * \param cb_arg Callback argument. | |
90 | * \param bs Handle to a blobstore. | |
91 | * \param bserrno 0 if it completed successfully, or negative errno if it failed. | |
92 | */ | |
7c673cae FG |
93 | typedef void (*spdk_bs_op_with_handle_complete)(void *cb_arg, struct spdk_blob_store *bs, |
94 | int bserrno); | |
11fdf7f2 TL |
95 | |
96 | /** | |
97 | * Blob operation completion callback. | |
98 | * | |
99 | * \param cb_arg Callback argument. | |
100 | * \param bserrno 0 if it completed successfully, or negative errno if it failed. | |
101 | */ | |
7c673cae | 102 | typedef void (*spdk_blob_op_complete)(void *cb_arg, int bserrno); |
11fdf7f2 TL |
103 | |
104 | /** | |
105 | * Blob operation completion callback with blob ID. | |
106 | * | |
107 | * \param cb_arg Callback argument. | |
108 | * \param blobid Blob ID. | |
109 | * \param bserrno 0 if it completed successfully, or negative errno if it failed. | |
110 | */ | |
7c673cae | 111 | typedef void (*spdk_blob_op_with_id_complete)(void *cb_arg, spdk_blob_id blobid, int bserrno); |
7c673cae | 112 | |
11fdf7f2 TL |
113 | /** |
114 | * Blob operation completion callback with handle. | |
115 | * | |
116 | * \param cb_arg Callback argument. | |
117 | * \param bs Handle to a blob. | |
118 | * \param bserrno 0 if it completed successfully, or negative errno if it failed. | |
119 | */ | |
120 | typedef void (*spdk_blob_op_with_handle_complete)(void *cb_arg, struct spdk_blob *blb, int bserrno); | |
7c673cae | 121 | |
11fdf7f2 TL |
122 | /** |
123 | * Blobstore device completion callback. | |
124 | * | |
125 | * \param channel I/O channel the operation was initiated on. | |
126 | * \param cb_arg Callback argument. | |
127 | * \param bserrno 0 if it completed successfully, or negative errno if it failed. | |
128 | */ | |
7c673cae FG |
129 | typedef void (*spdk_bs_dev_cpl)(struct spdk_io_channel *channel, |
130 | void *cb_arg, int bserrno); | |
131 | ||
132 | struct spdk_bs_dev_cb_args { | |
133 | spdk_bs_dev_cpl cb_fn; | |
134 | struct spdk_io_channel *channel; | |
135 | void *cb_arg; | |
7c673cae FG |
136 | }; |
137 | ||
138 | struct spdk_bs_dev { | |
139 | /* Create a new channel which is a software construct that is used | |
140 | * to submit I/O. */ | |
141 | struct spdk_io_channel *(*create_channel)(struct spdk_bs_dev *dev); | |
142 | ||
143 | /* Destroy a previously created channel */ | |
144 | void (*destroy_channel)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel); | |
145 | ||
146 | /* Destroy this blobstore device. Applications must not destroy the blobstore device, | |
147 | * rather the blobstore will destroy it using this function pointer once all | |
148 | * references to it during unload callback context have been completed. | |
149 | */ | |
150 | void (*destroy)(struct spdk_bs_dev *dev); | |
151 | ||
152 | void (*read)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, void *payload, | |
153 | uint64_t lba, uint32_t lba_count, | |
154 | struct spdk_bs_dev_cb_args *cb_args); | |
155 | ||
156 | void (*write)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, void *payload, | |
157 | uint64_t lba, uint32_t lba_count, | |
158 | struct spdk_bs_dev_cb_args *cb_args); | |
159 | ||
11fdf7f2 TL |
160 | void (*readv)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, |
161 | struct iovec *iov, int iovcnt, | |
162 | uint64_t lba, uint32_t lba_count, | |
163 | struct spdk_bs_dev_cb_args *cb_args); | |
164 | ||
165 | void (*writev)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, | |
166 | struct iovec *iov, int iovcnt, | |
167 | uint64_t lba, uint32_t lba_count, | |
168 | struct spdk_bs_dev_cb_args *cb_args); | |
169 | ||
7c673cae FG |
170 | void (*flush)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, |
171 | struct spdk_bs_dev_cb_args *cb_args); | |
172 | ||
11fdf7f2 TL |
173 | void (*write_zeroes)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, |
174 | uint64_t lba, uint32_t lba_count, | |
175 | struct spdk_bs_dev_cb_args *cb_args); | |
176 | ||
7c673cae FG |
177 | void (*unmap)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, |
178 | uint64_t lba, uint32_t lba_count, | |
179 | struct spdk_bs_dev_cb_args *cb_args); | |
180 | ||
181 | uint64_t blockcnt; | |
182 | uint32_t blocklen; /* In bytes */ | |
183 | }; | |
184 | ||
11fdf7f2 TL |
185 | struct spdk_bs_type { |
186 | char bstype[SPDK_BLOBSTORE_TYPE_LENGTH]; | |
187 | }; | |
188 | ||
7c673cae | 189 | struct spdk_bs_opts { |
11fdf7f2 TL |
190 | /** Size of cluster in bytes. Must be multiple of 4KiB page size. */ |
191 | uint32_t cluster_sz; | |
192 | ||
193 | /** Count of the number of pages reserved for metadata */ | |
194 | uint32_t num_md_pages; | |
195 | ||
196 | /** Maximum simultaneous metadata operations */ | |
197 | uint32_t max_md_ops; | |
198 | ||
199 | /** Maximum simultaneous operations per channel */ | |
200 | uint32_t max_channel_ops; | |
201 | ||
202 | /** Blobstore type */ | |
203 | struct spdk_bs_type bstype; | |
204 | ||
205 | /** Callback function to invoke for each blob. */ | |
206 | spdk_blob_op_with_handle_complete iter_cb_fn; | |
207 | ||
208 | /** Argument passed to iter_cb_fn for each blob. */ | |
209 | void *iter_cb_arg; | |
7c673cae FG |
210 | }; |
211 | ||
11fdf7f2 TL |
212 | /** |
213 | * Initialize a spdk_bs_opts structure to the default blobstore option values. | |
214 | * | |
215 | * \param opts The spdk_bs_opts structure to be initialized. | |
216 | */ | |
7c673cae FG |
217 | void spdk_bs_opts_init(struct spdk_bs_opts *opts); |
218 | ||
11fdf7f2 TL |
219 | /** |
220 | * Load a blobstore from the given device. | |
221 | * | |
222 | * \param dev Blobstore block device. | |
223 | * \param opts The structure which contains the option values for the blobstore. | |
224 | * \param cb_fn Called when the loading is complete. | |
225 | * \param cb_arg Argument passed to function cb_fn. | |
226 | */ | |
227 | void spdk_bs_load(struct spdk_bs_dev *dev, struct spdk_bs_opts *opts, | |
7c673cae FG |
228 | spdk_bs_op_with_handle_complete cb_fn, void *cb_arg); |
229 | ||
11fdf7f2 TL |
230 | /** |
231 | * Initialize a blobstore on the given device. | |
232 | * | |
233 | * \param dev Blobstore block device. | |
234 | * \param opts The structure which contains the option values for the blobstore. | |
235 | * \param cb_fn Called when the initialization is complete. | |
236 | * \param cb_arg Argument passed to function cb_fn. | |
237 | */ | |
7c673cae FG |
238 | void spdk_bs_init(struct spdk_bs_dev *dev, struct spdk_bs_opts *opts, |
239 | spdk_bs_op_with_handle_complete cb_fn, void *cb_arg); | |
240 | ||
11fdf7f2 TL |
241 | typedef void (*spdk_bs_dump_print_xattr)(FILE *fp, const char *bstype, const char *name, |
242 | const void *value, size_t value_length); | |
243 | ||
244 | /** | |
245 | * Dump a blobstore's metadata to a given FILE in human-readable format. | |
246 | * | |
247 | * \param dev Blobstore block device. | |
248 | * \param fp FILE pointer to dump the metadata contents. | |
249 | * \param print_xattr_fn Callback function to interpret external xattrs. | |
250 | * \param cb_fn Called when the dump is complete. | |
251 | * \param cb_arg Argument passed to function cb_fn. | |
252 | */ | |
253 | void spdk_bs_dump(struct spdk_bs_dev *dev, FILE *fp, spdk_bs_dump_print_xattr print_xattr_fn, | |
254 | spdk_bs_op_complete cb_fn, void *cb_arg); | |
255 | /** | |
256 | * Destroy the blobstore. | |
257 | * | |
258 | * It will destroy the blobstore by zeroing the super block. | |
259 | * | |
260 | * \param bs blobstore to destroy. | |
261 | * \param cb_fn Called when the destruction is complete. | |
262 | * \param cb_arg Argument passed to function cb_fn. | |
263 | */ | |
264 | void spdk_bs_destroy(struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, | |
265 | void *cb_arg); | |
266 | ||
267 | /** | |
268 | * Unload the blobstore. | |
269 | * | |
270 | * It will flush all volatile data to disk. | |
271 | * | |
272 | * \param bs blobstore to unload. | |
273 | * \param cb_fn Called when the unloading is complete. | |
274 | * \param cb_arg Argument passed to function cb_fn. | |
275 | */ | |
7c673cae FG |
276 | void spdk_bs_unload(struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg); |
277 | ||
11fdf7f2 TL |
278 | /** |
279 | * Set a super blob on the given blobstore. | |
280 | * | |
281 | * This will be retrievable immediately after spdk_bs_load() on the next initializaiton. | |
282 | * | |
283 | * \param bs blobstore. | |
284 | * \param blobid The id of the blob which will be set as the super blob. | |
285 | * \param cb_fn Called when the setting is complete. | |
286 | * \param cb_arg Argument passed to function cb_fn. | |
7c673cae FG |
287 | */ |
288 | void spdk_bs_set_super(struct spdk_blob_store *bs, spdk_blob_id blobid, | |
289 | spdk_bs_op_complete cb_fn, void *cb_arg); | |
290 | ||
11fdf7f2 TL |
291 | /** |
292 | * Get the super blob. The obtained blob id will be passed to the callback function. | |
293 | * | |
294 | * \param bs blobstore. | |
295 | * \param cb_fn Called when the operation is complete. | |
296 | * \param cb_arg Argument passed to function cb_fn. | |
297 | */ | |
7c673cae FG |
298 | void spdk_bs_get_super(struct spdk_blob_store *bs, |
299 | spdk_blob_op_with_id_complete cb_fn, void *cb_arg); | |
300 | ||
11fdf7f2 TL |
301 | /** |
302 | * Get the cluster size in bytes. | |
303 | * | |
304 | * \param bs blobstore to query. | |
305 | * | |
306 | * \return cluster size. | |
307 | */ | |
7c673cae FG |
308 | uint64_t spdk_bs_get_cluster_size(struct spdk_blob_store *bs); |
309 | ||
11fdf7f2 TL |
310 | /** |
311 | * Get the page size in bytes. This is the write and read granularity of blobs. | |
312 | * | |
313 | * \param bs blobstore to query. | |
314 | * | |
315 | * \return page size. | |
316 | */ | |
7c673cae FG |
317 | uint64_t spdk_bs_get_page_size(struct spdk_blob_store *bs); |
318 | ||
11fdf7f2 TL |
319 | /** |
320 | * Get the io unit size in bytes. | |
321 | * | |
322 | * \param bs blobstore to query. | |
323 | * | |
324 | * \return io unit size. | |
325 | */ | |
326 | uint64_t spdk_bs_get_io_unit_size(struct spdk_blob_store *bs); | |
7c673cae | 327 | |
11fdf7f2 TL |
328 | /** |
329 | * Get the number of free clusters. | |
330 | * | |
331 | * \param bs blobstore to query. | |
332 | * | |
333 | * \return the number of free clusters. | |
7c673cae | 334 | */ |
11fdf7f2 | 335 | uint64_t spdk_bs_free_cluster_count(struct spdk_blob_store *bs); |
7c673cae | 336 | |
11fdf7f2 TL |
337 | /** |
338 | * Get the total number of clusters accessible by user. | |
339 | * | |
340 | * \param bs blobstore to query. | |
341 | * | |
342 | * \return the total number of clusters accessible by user. | |
7c673cae | 343 | */ |
11fdf7f2 | 344 | uint64_t spdk_bs_total_data_cluster_count(struct spdk_blob_store *bs); |
7c673cae | 345 | |
11fdf7f2 TL |
346 | /** |
347 | * Get the blob id. | |
348 | * | |
349 | * \param blob Blob struct to query. | |
350 | * | |
351 | * \return blob id. | |
352 | */ | |
7c673cae FG |
353 | spdk_blob_id spdk_blob_get_id(struct spdk_blob *blob); |
354 | ||
11fdf7f2 TL |
355 | /** |
356 | * Get the number of pages allocated to the blob. | |
357 | * | |
358 | * \param blob Blob struct to query. | |
359 | * | |
360 | * \return the number of pages. | |
361 | */ | |
7c673cae FG |
362 | uint64_t spdk_blob_get_num_pages(struct spdk_blob *blob); |
363 | ||
11fdf7f2 TL |
364 | /** |
365 | * Get the number of io_units allocated to the blob. | |
366 | * | |
367 | * \param blob Blob struct to query. | |
368 | * | |
369 | * \return the number of io_units. | |
370 | */ | |
371 | uint64_t spdk_blob_get_num_io_units(struct spdk_blob *blob); | |
372 | ||
373 | /** | |
374 | * Get the number of clusters allocated to the blob. | |
375 | * | |
376 | * \param blob Blob struct to query. | |
377 | * | |
378 | * \return the number of clusters. | |
379 | */ | |
7c673cae FG |
380 | uint64_t spdk_blob_get_num_clusters(struct spdk_blob *blob); |
381 | ||
11fdf7f2 TL |
382 | struct spdk_blob_xattr_opts { |
383 | /* Number of attributes */ | |
384 | size_t count; | |
385 | /* Array of attribute names. Caller should free this array after use. */ | |
386 | char **names; | |
387 | /* User context passed to get_xattr_value function */ | |
388 | void *ctx; | |
389 | /* Callback that will return value for each attribute name. */ | |
390 | void (*get_value)(void *xattr_ctx, const char *name, | |
391 | const void **value, size_t *value_len); | |
392 | }; | |
393 | ||
394 | struct spdk_blob_opts { | |
395 | uint64_t num_clusters; | |
396 | bool thin_provision; | |
397 | struct spdk_blob_xattr_opts xattrs; | |
398 | }; | |
399 | ||
400 | /** | |
401 | * Initialize a spdk_blob_opts structure to the default blob option values. | |
402 | * | |
403 | * \param opts spdk_blob_opts structure to initialize. | |
404 | */ | |
405 | void spdk_blob_opts_init(struct spdk_blob_opts *opts); | |
406 | ||
407 | /** | |
408 | * Create a new blob with options on the given blobstore. The new blob id will | |
409 | * be passed to the callback function. | |
410 | * | |
411 | * \param bs blobstore. | |
412 | * \param opts The structure which contains the option values for the new blob. | |
413 | * \param cb_fn Called when the operation is complete. | |
414 | * \param cb_arg Argument passed to funcion cb_fn. | |
415 | */ | |
416 | void spdk_bs_create_blob_ext(struct spdk_blob_store *bs, const struct spdk_blob_opts *opts, | |
417 | spdk_blob_op_with_id_complete cb_fn, void *cb_arg); | |
418 | ||
419 | /** | |
420 | * Create a new blob with default option values on the given blobstore. | |
421 | * The new blob id will be passed to the callback function. | |
422 | * | |
423 | * \param bs blobstore. | |
424 | * \param cb_fn Called when the operation is complete. | |
425 | * \param cb_arg Argument passed to function cb_fn. | |
426 | */ | |
427 | void spdk_bs_create_blob(struct spdk_blob_store *bs, | |
428 | spdk_blob_op_with_id_complete cb_fn, void *cb_arg); | |
429 | ||
430 | /** | |
431 | * Create a read-only snapshot of specified blob with provided options. | |
432 | * This will automatically sync specified blob. | |
433 | * | |
434 | * When operation is done, original blob is converted to the thin-provisioned | |
435 | * blob with a newly created read-only snapshot set as a backing blob. | |
436 | * Structure snapshot_xattrs as well as anything it references (like e.g. names | |
437 | * array) must be valid until the completion is called. | |
438 | * | |
439 | * \param bs blobstore. | |
440 | * \param blobid Id of the source blob used to create a snapshot. | |
441 | * \param snapshot_xattrs xattrs specified for snapshot. | |
442 | * \param cb_fn Called when the operation is complete. | |
443 | * \param cb_arg Argument passed to function cb_fn. | |
444 | */ | |
445 | void spdk_bs_create_snapshot(struct spdk_blob_store *bs, spdk_blob_id blobid, | |
446 | const struct spdk_blob_xattr_opts *snapshot_xattrs, | |
447 | spdk_blob_op_with_id_complete cb_fn, void *cb_arg); | |
448 | ||
449 | /** | |
450 | * Create a clone of specified read-only blob. | |
451 | * | |
452 | * Structure clone_xattrs as well as anything it references (like e.g. names | |
453 | * array) must be valid until the completion is called. | |
454 | * | |
455 | * \param bs blobstore. | |
456 | * \param blobid Id of the read only blob used as a snapshot for new clone. | |
457 | * \param clone_xattrs xattrs specified for clone. | |
458 | * \param cb_fn Called when the operation is complete. | |
459 | * \param cb_arg Argument passed to function cb_fn. | |
460 | */ | |
461 | void spdk_bs_create_clone(struct spdk_blob_store *bs, spdk_blob_id blobid, | |
462 | const struct spdk_blob_xattr_opts *clone_xattrs, | |
463 | spdk_blob_op_with_id_complete cb_fn, void *cb_arg); | |
464 | ||
465 | /** | |
466 | * Provide table with blob id's of clones are dependent on specified snapshot. | |
467 | * | |
468 | * Ids array should be allocated and the count parameter set to the number of | |
469 | * id's it can store, before calling this function. | |
470 | * | |
471 | * If ids is NULL or count parameter is not sufficient to handle ids of all | |
472 | * clones, -ENOMEM error is returned and count parameter is updated to the | |
473 | * total number of clones. | |
474 | * | |
475 | * \param bs blobstore. | |
476 | * \param blobid Snapshots blob id. | |
477 | * \param ids Array of the clone ids or NULL to get required size in count. | |
478 | * \param count Size of ids. After call it is updated to the number of clones. | |
479 | * | |
480 | * \return -ENOMEM if count is not sufficient to store all clones. | |
481 | */ | |
482 | int spdk_blob_get_clones(struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_blob_id *ids, | |
483 | size_t *count); | |
484 | ||
485 | /** | |
486 | * Get the blob id for the parent snapshot of this blob. | |
487 | * | |
488 | * \param bs blobstore. | |
489 | * \param blobid Blob id. | |
490 | * | |
491 | * \return blob id of parent blob or SPDK_BLOBID_INVALID if have no parent | |
492 | */ | |
493 | spdk_blob_id spdk_blob_get_parent_snapshot(struct spdk_blob_store *bs, spdk_blob_id blobid); | |
494 | ||
495 | /** | |
496 | * Check if blob is read only. | |
497 | * | |
498 | * \param blob Blob. | |
499 | * | |
500 | * \return true if blob is read only. | |
501 | */ | |
502 | bool spdk_blob_is_read_only(struct spdk_blob *blob); | |
503 | ||
504 | /** | |
505 | * Check if blob is a snapshot. | |
506 | * | |
507 | * \param blob Blob. | |
508 | * | |
509 | * \return true if blob is a snapshot. | |
510 | */ | |
511 | bool spdk_blob_is_snapshot(struct spdk_blob *blob); | |
512 | ||
513 | /** | |
514 | * Check if blob is a clone. | |
515 | * | |
516 | * \param blob Blob. | |
517 | * | |
518 | * \return true if blob is a clone. | |
519 | */ | |
520 | bool spdk_blob_is_clone(struct spdk_blob *blob); | |
521 | ||
522 | /** | |
523 | * Check if blob is thin-provisioned. | |
524 | * | |
525 | * \param blob Blob. | |
526 | * | |
527 | * \return true if blob is thin-provisioned. | |
528 | */ | |
529 | bool spdk_blob_is_thin_provisioned(struct spdk_blob *blob); | |
530 | ||
531 | /** | |
532 | * Delete an existing blob from the given blobstore. | |
533 | * | |
534 | * \param bs blobstore. | |
535 | * \param blobid The id of the blob to delete. | |
536 | * \param cb_fn Called when the operation is complete. | |
537 | * \param cb_arg Argument passed to function cb_fn. | |
538 | */ | |
539 | void spdk_bs_delete_blob(struct spdk_blob_store *bs, spdk_blob_id blobid, | |
540 | spdk_blob_op_complete cb_fn, void *cb_arg); | |
7c673cae | 541 | |
11fdf7f2 TL |
542 | /** |
543 | * Allocate all clusters in this blob. Data for allocated clusters is copied | |
544 | * from backing blob(s) if they exist. | |
545 | * | |
546 | * This call removes all dependencies on any backing blobs. | |
547 | * | |
548 | * \param bs blobstore. | |
549 | * \param channel IO channel used to inflate blob. | |
550 | * \param blobid The id of the blob to inflate. | |
551 | * \param cb_fn Called when the operation is complete. | |
552 | * \param cb_arg Argument passed to function cb_fn. | |
553 | */ | |
554 | void spdk_bs_inflate_blob(struct spdk_blob_store *bs, struct spdk_io_channel *channel, | |
555 | spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg); | |
556 | ||
557 | /** | |
558 | * Remove dependency on parent blob. | |
559 | * | |
560 | * This call allocates and copies data for any clusters that are allocated in | |
561 | * the parent blob, and decouples parent updating dependencies of blob to | |
562 | * its ancestor. | |
563 | * | |
564 | * If blob have no parent -EINVAL error is reported. | |
565 | * | |
566 | * \param bs blobstore. | |
567 | * \param channel IO channel used to inflate blob. | |
568 | * \param blobid The id of the blob. | |
569 | * \param cb_fn Called when the operation is complete. | |
570 | * \param cb_arg Argument passed to function cb_fn. | |
571 | */ | |
572 | void spdk_bs_blob_decouple_parent(struct spdk_blob_store *bs, struct spdk_io_channel *channel, | |
573 | spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg); | |
574 | ||
575 | /** | |
576 | * Open a blob from the given blobstore. | |
577 | * | |
578 | * \param bs blobstore. | |
579 | * \param blobid The id of the blob to open. | |
580 | * \param cb_fn Called when the operation is complete. | |
581 | * \param cb_arg Argument passed to function cb_fn. | |
582 | */ | |
583 | void spdk_bs_open_blob(struct spdk_blob_store *bs, spdk_blob_id blobid, | |
584 | spdk_blob_op_with_handle_complete cb_fn, void *cb_arg); | |
7c673cae | 585 | |
11fdf7f2 TL |
586 | /** |
587 | * Resize a blob to 'sz' clusters. These changes are not persisted to disk until | |
588 | * spdk_bs_md_sync_blob() is called. | |
589 | * If called before previous resize finish, it will fail with errno -EBUSY | |
590 | * | |
591 | * \param blob Blob to resize. | |
592 | * \param sz The new number of clusters. | |
593 | * \param cb_fn Called when the operation is complete. | |
594 | * \param cb_arg Argument passed to function cb_fn. | |
595 | * | |
596 | */ | |
597 | void spdk_blob_resize(struct spdk_blob *blob, uint64_t sz, spdk_blob_op_complete cb_fn, | |
598 | void *cb_arg); | |
7c673cae | 599 | |
11fdf7f2 TL |
600 | /** |
601 | * Set blob as read only. | |
602 | * | |
603 | * These changes do not take effect until spdk_blob_sync_md() is called. | |
7c673cae | 604 | * |
11fdf7f2 TL |
605 | * \param blob Blob to set. |
606 | */ | |
607 | int spdk_blob_set_read_only(struct spdk_blob *blob); | |
7c673cae | 608 | |
11fdf7f2 TL |
609 | /** |
610 | * Sync a blob. | |
611 | * | |
612 | * Make a blob persistent. This applies to open, resize, set xattr, and remove | |
613 | * xattr. These operations will not be persistent until the blob has been synced. | |
7c673cae | 614 | * |
11fdf7f2 TL |
615 | * \param blob Blob to sync. |
616 | * \param cb_fn Called when the operation is complete. | |
617 | * \param cb_arg Argument passed to function cb_fn. | |
7c673cae | 618 | */ |
11fdf7f2 | 619 | void spdk_blob_sync_md(struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg); |
7c673cae | 620 | |
11fdf7f2 TL |
621 | /** |
622 | * Close a blob. This will automatically sync. | |
623 | * | |
624 | * \param blob Blob to close. | |
625 | * \param cb_fn Called when the operation is complete. | |
626 | * \param cb_arg Argument passed to function cb_fn. | |
627 | */ | |
628 | void spdk_blob_close(struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg); | |
7c673cae | 629 | |
11fdf7f2 TL |
630 | /** |
631 | * Allocate an I/O channel for the given blobstore. | |
632 | * | |
633 | * \param bs blobstore. | |
634 | * \return a pointer to the allocated I/O channel. | |
635 | */ | |
636 | struct spdk_io_channel *spdk_bs_alloc_io_channel(struct spdk_blob_store *bs); | |
7c673cae | 637 | |
11fdf7f2 TL |
638 | /** |
639 | * Free the I/O channel. | |
640 | * | |
641 | * \param channel I/O channel to free. | |
642 | */ | |
7c673cae FG |
643 | void spdk_bs_free_io_channel(struct spdk_io_channel *channel); |
644 | ||
11fdf7f2 TL |
645 | /** |
646 | * Write data to a blob. | |
647 | * | |
648 | * \param blob Blob to write. | |
649 | * \param channel The I/O channel used to submit requests. | |
650 | * \param payload The specified buffer which should contain the data to be written. | |
651 | * \param offset Offset is in io units from the beginning of the blob. | |
652 | * \param length Size of data in io units. | |
653 | * \param cb_fn Called when the operation is complete. | |
654 | * \param cb_arg Argument passed to function cb_fn. | |
655 | */ | |
656 | void spdk_blob_io_write(struct spdk_blob *blob, struct spdk_io_channel *channel, | |
657 | void *payload, uint64_t offset, uint64_t length, | |
658 | spdk_blob_op_complete cb_fn, void *cb_arg); | |
659 | ||
660 | /** | |
661 | * Read data from a blob. | |
662 | * | |
663 | * \param blob Blob to read. | |
664 | * \param channel The I/O channel used to submit requests. | |
665 | * \param payload The specified buffer which will store the obtained data. | |
666 | * \param offset Offset is in io units from the beginning of the blob. | |
667 | * \param length Size of data in io units. | |
668 | * \param cb_fn Called when the operation is complete. | |
669 | * \param cb_arg Argument passed to function cb_fn. | |
670 | */ | |
671 | void spdk_blob_io_read(struct spdk_blob *blob, struct spdk_io_channel *channel, | |
672 | void *payload, uint64_t offset, uint64_t length, | |
673 | spdk_blob_op_complete cb_fn, void *cb_arg); | |
674 | ||
675 | /** | |
676 | * Write the data described by 'iov' to 'length' pages beginning at 'offset' pages | |
677 | * into the blob. | |
678 | * | |
679 | * \param blob Blob to write. | |
680 | * \param channel I/O channel used to submit requests. | |
681 | * \param iov The pointer points to an array of iovec structures. | |
682 | * \param iovcnt The number of buffers. | |
683 | * \param offset Offset is in io units from the beginning of the blob. | |
684 | * \param length Size of data in io units. | |
685 | * \param cb_fn Called when the operation is complete. | |
686 | * \param cb_arg Argument passed to function cb_fn. | |
687 | */ | |
688 | void spdk_blob_io_writev(struct spdk_blob *blob, struct spdk_io_channel *channel, | |
689 | struct iovec *iov, int iovcnt, uint64_t offset, uint64_t length, | |
690 | spdk_blob_op_complete cb_fn, void *cb_arg); | |
691 | ||
692 | /** | |
693 | * Read 'length' pages starting at 'offset' pages into the blob into the memory | |
694 | * described by 'iov'. | |
695 | * | |
696 | * \param blob Blob to read. | |
697 | * \param channel I/O channel used to submit requests. | |
698 | * \param iov The pointer points to an array of iovec structures. | |
699 | * \param iovcnt The number of buffers. | |
700 | * \param offset Offset is in io units from the beginning of the blob. | |
701 | * \param length Size of data in io units. | |
702 | * \param cb_fn Called when the operation is complete. | |
703 | * \param cb_arg Argument passed to function cb_fn. | |
704 | */ | |
705 | void spdk_blob_io_readv(struct spdk_blob *blob, struct spdk_io_channel *channel, | |
706 | struct iovec *iov, int iovcnt, uint64_t offset, uint64_t length, | |
707 | spdk_blob_op_complete cb_fn, void *cb_arg); | |
708 | ||
709 | /** | |
710 | * Unmap 'length' pages beginning at 'offset' pages on the blob as unused. Unmapped | |
711 | * pages may allow the underlying storage media to behave more effciently. | |
712 | * | |
713 | * \param blob Blob to unmap. | |
714 | * \param channel I/O channel used to submit requests. | |
715 | * \param offset Offset is in io units from the beginning of the blob. | |
716 | * \param length Size of unmap area in pages. | |
717 | * \param cb_fn Called when the operation is complete. | |
718 | * \param cb_arg Argument passed to function cb_fn. | |
719 | */ | |
720 | void spdk_blob_io_unmap(struct spdk_blob *blob, struct spdk_io_channel *channel, | |
721 | uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); | |
7c673cae | 722 | |
11fdf7f2 TL |
723 | /** |
724 | * Write zeros into area of a blob. | |
725 | * | |
726 | * \param blob Blob to write. | |
727 | * \param channel I/O channel used to submit requests. | |
728 | * \param offset Offset is in io units from the beginning of the blob. | |
729 | * \param length Size of data in io units. | |
730 | * \param cb_fn Called when the operation is complete. | |
731 | * \param cb_arg Argument passed to function cb_fn. | |
732 | */ | |
733 | void spdk_blob_io_write_zeroes(struct spdk_blob *blob, struct spdk_io_channel *channel, | |
734 | uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); | |
7c673cae | 735 | |
11fdf7f2 TL |
736 | /** |
737 | * Get the first blob of the blobstore. The obtained blob will be passed to | |
738 | * the callback function. | |
739 | * | |
740 | * \param bs blobstore to traverse. | |
741 | * \param cb_fn Called when the operation is complete. | |
742 | * \param cb_arg Argument passed to function cb_fn. | |
743 | */ | |
744 | void spdk_bs_iter_first(struct spdk_blob_store *bs, | |
745 | spdk_blob_op_with_handle_complete cb_fn, void *cb_arg); | |
7c673cae | 746 | |
11fdf7f2 TL |
747 | /** |
748 | * Get the next blob by using the current blob. The obtained blob will be passed | |
749 | * to the callback function. | |
750 | * | |
751 | * \param bs blobstore to traverse. | |
752 | * \param blob The current blob. | |
753 | * \param cb_fn Called when the operation is complete. | |
754 | * \param cb_arg Argument passed to function cb_fn. | |
755 | */ | |
756 | void spdk_bs_iter_next(struct spdk_blob_store *bs, struct spdk_blob *blob, | |
757 | spdk_blob_op_with_handle_complete cb_fn, void *cb_arg); | |
7c673cae | 758 | |
11fdf7f2 TL |
759 | /** |
760 | * Set an extended attribute for the given blob. | |
761 | * | |
762 | * \param blob Blob to set attribute. | |
763 | * \param name Name of the extended attribute. | |
764 | * \param value Value of the extended attribute. | |
765 | * \param value_len Length of the value. | |
766 | * | |
767 | * \return 0 on success, -1 on failure. | |
768 | */ | |
769 | int spdk_blob_set_xattr(struct spdk_blob *blob, const char *name, const void *value, | |
770 | uint16_t value_len); | |
7c673cae | 771 | |
11fdf7f2 TL |
772 | /** |
773 | * Remove the extended attribute from the given blob. | |
774 | * | |
775 | * \param blob Blob to remove attribute. | |
776 | * \param name Name of the extended attribute. | |
777 | * | |
778 | * \return 0 on success, negative errno on failure. | |
779 | */ | |
780 | int spdk_blob_remove_xattr(struct spdk_blob *blob, const char *name); | |
7c673cae | 781 | |
11fdf7f2 TL |
782 | /** |
783 | * Get the value of the specified extended attribute. The obtained value and its | |
784 | * size will be stored in value and value_len. | |
785 | * | |
786 | * \param blob Blob to query. | |
787 | * \param name Name of the extended attribute. | |
788 | * \param value Parameter as output. | |
789 | * \param value_len Parameter as output. | |
790 | * | |
791 | * \return 0 on success, negative errno on failure. | |
792 | */ | |
793 | int spdk_blob_get_xattr_value(struct spdk_blob *blob, const char *name, | |
794 | const void **value, size_t *value_len); | |
795 | ||
796 | /** | |
797 | * Iterate through all extended attributes of the blob. Get the names of all extended | |
798 | * attributes that will be stored in names. | |
799 | * | |
800 | * \param blob Blob to query. | |
801 | * \param names Parameter as output. | |
802 | * | |
803 | * \return 0 on success, negative errno on failure. | |
804 | */ | |
805 | int spdk_blob_get_xattr_names(struct spdk_blob *blob, struct spdk_xattr_names **names); | |
806 | ||
807 | /** | |
808 | * Get the number of extended attributes. | |
809 | * | |
810 | * \param names Names of total extended attributes of the blob. | |
811 | * | |
812 | * \return the number of extended attributes. | |
813 | */ | |
7c673cae | 814 | uint32_t spdk_xattr_names_get_count(struct spdk_xattr_names *names); |
11fdf7f2 TL |
815 | |
816 | /** | |
817 | * Get the attribute name specified by the index. | |
818 | * | |
819 | * \param names Names of total extended attributes of the blob. | |
820 | * \param index Index position of the specified attribute. | |
821 | * | |
822 | * \return attribute name. | |
823 | */ | |
7c673cae | 824 | const char *spdk_xattr_names_get_name(struct spdk_xattr_names *names, uint32_t index); |
11fdf7f2 TL |
825 | |
826 | /** | |
827 | * Free the attribute names. | |
828 | * | |
829 | * \param names Names of total extended attributes of the blob. | |
830 | */ | |
7c673cae FG |
831 | void spdk_xattr_names_free(struct spdk_xattr_names *names); |
832 | ||
11fdf7f2 TL |
833 | /** |
834 | * Get blobstore type of the given device. | |
835 | * | |
836 | * \param bs blobstore to query. | |
837 | * | |
838 | * \return blobstore type. | |
839 | */ | |
840 | struct spdk_bs_type spdk_bs_get_bstype(struct spdk_blob_store *bs); | |
841 | ||
842 | /** | |
843 | * Set blobstore type to the given device. | |
844 | * | |
845 | * \param bs blobstore to set to. | |
846 | * \param bstype Type label to set. | |
847 | */ | |
848 | void spdk_bs_set_bstype(struct spdk_blob_store *bs, struct spdk_bs_type bstype); | |
849 | ||
850 | #ifdef __cplusplus | |
851 | } | |
852 | #endif | |
853 | ||
7c673cae | 854 | #endif /* SPDK_BLOB_H_ */ |