]>
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 | * SPDK Filesystem | |
36 | */ | |
37 | ||
38 | #ifndef SPDK_FS_H | |
39 | #define SPDK_FS_H | |
40 | ||
11fdf7f2 | 41 | #include "spdk/stdinc.h" |
7c673cae FG |
42 | |
43 | #include "spdk/blob.h" | |
44 | ||
11fdf7f2 TL |
45 | #ifdef __cplusplus |
46 | extern "C" { | |
47 | #endif | |
48 | ||
7c673cae FG |
49 | #define SPDK_FILE_NAME_MAX 255 |
50 | ||
51 | struct spdk_file; | |
52 | struct spdk_filesystem; | |
53 | ||
54 | typedef struct spdk_file *spdk_fs_iter; | |
55 | ||
11fdf7f2 TL |
56 | struct spdk_blobfs_opts { |
57 | uint32_t cluster_sz; | |
58 | }; | |
59 | ||
7c673cae FG |
60 | struct spdk_file_stat { |
61 | spdk_blob_id blobid; | |
62 | uint64_t size; | |
63 | }; | |
64 | ||
11fdf7f2 TL |
65 | /** |
66 | * Filesystem operation completion callback with handle. | |
67 | * | |
68 | * \param ctx Context for the operation. | |
69 | * \param fs Handle to a blobfs. | |
70 | * \param fserrno 0 if it completed successfully, or negative errno if it failed. | |
71 | */ | |
7c673cae FG |
72 | typedef void (*spdk_fs_op_with_handle_complete)(void *ctx, struct spdk_filesystem *fs, |
73 | int fserrno); | |
11fdf7f2 TL |
74 | |
75 | /** | |
76 | * File operation completion callback with handle. | |
77 | * | |
78 | * \param ctx Context for the operation. | |
79 | * \param f Handle to a file. | |
80 | * \param fserrno 0 if it completed successfully, or negative errno if it failed. | |
81 | */ | |
7c673cae FG |
82 | typedef void (*spdk_file_op_with_handle_complete)(void *ctx, struct spdk_file *f, int fserrno); |
83 | typedef spdk_bs_op_complete spdk_fs_op_complete; | |
84 | ||
11fdf7f2 TL |
85 | /** |
86 | * File operation completion callback. | |
87 | * | |
88 | * \param ctx Context for the operation. | |
89 | * \param fserrno 0 if it completed successfully, or negative errno if it failed. | |
90 | */ | |
7c673cae | 91 | typedef void (*spdk_file_op_complete)(void *ctx, int fserrno); |
11fdf7f2 TL |
92 | |
93 | /** | |
94 | * File stat operation completion callback. | |
95 | * | |
96 | * \param ctx Context for the operation. | |
97 | * \param stat Handle to the stat about the file. | |
98 | * \param fserrno 0 if it completed successfully, or negative errno if it failed. | |
99 | */ | |
7c673cae FG |
100 | typedef void (*spdk_file_stat_op_complete)(void *ctx, struct spdk_file_stat *stat, int fserrno); |
101 | ||
11fdf7f2 TL |
102 | /** |
103 | * Function for a request of file system. | |
104 | * | |
105 | * \param arg Argument to the request function. | |
106 | */ | |
107 | typedef void (*fs_request_fn)(void *arg); | |
108 | ||
109 | /** | |
110 | * Function for sending request. | |
111 | * | |
112 | * This function will be invoked any time when the filesystem wants to pass a | |
113 | * message to the main dispatch thread. | |
114 | * | |
115 | * \param fs_request_fn A pointer to the request function. | |
116 | * \param arg Argument to the request function. | |
117 | */ | |
118 | typedef void (*fs_send_request_fn)(fs_request_fn, void *arg); | |
7c673cae | 119 | |
11fdf7f2 TL |
120 | /** |
121 | * Initialize a spdk_blobfs_opts structure to the default option values. | |
122 | * | |
123 | * \param opts spdk_blobf_opts struture to intialize. | |
124 | */ | |
125 | void spdk_fs_opts_init(struct spdk_blobfs_opts *opts); | |
126 | ||
127 | /** | |
128 | * Initialize blobstore filesystem. | |
129 | * | |
130 | * Initialize the blobstore filesystem on the blobstore block device which has | |
131 | * been created by the function spdk_bdev_create_bs_dev() in the blob_bdev.h. | |
132 | * The obtained blobstore filesystem will be passed to the callback function. | |
133 | * | |
134 | * \param dev Blobstore block device used by this blobstore filesystem. | |
135 | * \param opt Initialization options used for this blobstore filesystem. | |
136 | * \param send_request_fn The function for sending request. This function will | |
137 | * be invoked any time when the blobstore filesystem wants to pass a message to | |
138 | * the main dispatch thread. | |
139 | * \param cb_fn Called when the initialization is complete. | |
140 | * \param cb_arg Argument passed to function cb_fn. | |
141 | */ | |
142 | void spdk_fs_init(struct spdk_bs_dev *dev, struct spdk_blobfs_opts *opt, | |
143 | fs_send_request_fn send_request_fn, | |
7c673cae | 144 | spdk_fs_op_with_handle_complete cb_fn, void *cb_arg); |
11fdf7f2 TL |
145 | |
146 | /** | |
147 | * Load blobstore filesystem from the given blobstore block device. | |
148 | * | |
149 | * The obtained blobstore filesystem will be passed to the callback function. | |
150 | * | |
151 | * \param dev Blobstore block device used by this blobstore filesystem. | |
152 | * \param send_request_fn The function for sending request. This function will | |
153 | * be invoked any time when the blobstore filesystem wants to pass a message to | |
154 | * the main dispatch thread. | |
155 | * \param cb_fn Called when the loading is complete. | |
156 | * \param cb_arg Argument passed to function cb_fn. | |
157 | */ | |
7c673cae FG |
158 | void spdk_fs_load(struct spdk_bs_dev *dev, fs_send_request_fn send_request_fn, |
159 | spdk_fs_op_with_handle_complete cb_fn, void *cb_arg); | |
11fdf7f2 TL |
160 | |
161 | /** | |
162 | * Unload blobstore filesystem. | |
163 | * | |
164 | * \param fs Blobstore filesystem to unload. | |
165 | * \param cb_fn Called when the unloading is complete. | |
166 | * \param cb_arg Argument passed to function cb_fn. | |
167 | */ | |
7c673cae FG |
168 | void spdk_fs_unload(struct spdk_filesystem *fs, spdk_fs_op_complete cb_fn, void *cb_arg); |
169 | ||
11fdf7f2 TL |
170 | /** |
171 | * Allocate an I/O channel for asynchronous operations. | |
172 | * | |
173 | * \param fs Blobstore filesystem to allocate I/O channel. | |
174 | * | |
175 | * \return a pointer to the I/O channel on success or NULL otherwise. | |
176 | */ | |
177 | struct spdk_io_channel *spdk_fs_alloc_io_channel(struct spdk_filesystem *fs); | |
7c673cae | 178 | |
11fdf7f2 TL |
179 | /** |
180 | * Allocate an I/O channel for synchronous operations. | |
181 | * | |
182 | * \param fs Blobstore filesystem to allocate I/O channel. | |
183 | * | |
184 | * \return a pointer to the I/O channel on success or NULL otherwise. | |
7c673cae | 185 | */ |
11fdf7f2 | 186 | struct spdk_io_channel *spdk_fs_alloc_io_channel_sync(struct spdk_filesystem *fs); |
7c673cae | 187 | |
11fdf7f2 TL |
188 | /** |
189 | * Free I/O channel. | |
190 | * | |
191 | * This function will decrease the references of this I/O channel. If the reference | |
192 | * is reduced to 0, the I/O channel will be freed. | |
193 | * | |
194 | * \param channel I/O channel to free. | |
195 | */ | |
7c673cae FG |
196 | void spdk_fs_free_io_channel(struct spdk_io_channel *channel); |
197 | ||
11fdf7f2 TL |
198 | /** |
199 | * Get statistics about the file including the underlying blob id and the file size. | |
200 | * | |
201 | * \param fs Blobstore filesystem. | |
202 | * \param channel The I/O channel used to allocate file request. | |
203 | * \param name The file name used to look up the matched file in the blobstore filesystem. | |
204 | * \param stat Caller allocated structure to store the obtained information about | |
205 | * this file. | |
206 | * | |
207 | * \return 0 on success, negative errno on failure. | |
208 | */ | |
7c673cae FG |
209 | int spdk_fs_file_stat(struct spdk_filesystem *fs, struct spdk_io_channel *channel, |
210 | const char *name, struct spdk_file_stat *stat); | |
211 | ||
212 | #define SPDK_BLOBFS_OPEN_CREATE (1ULL << 0) | |
213 | ||
11fdf7f2 TL |
214 | /** |
215 | * Create a new file on the given blobstore filesystem. | |
216 | * | |
217 | * \param fs Blobstore filesystem. | |
218 | * \param channel The I/O channel used to allocate file request. | |
219 | * \param name The file name for this new file. | |
220 | * | |
221 | * \return 0 on success, negative errno on failure. | |
222 | */ | |
7c673cae FG |
223 | int spdk_fs_create_file(struct spdk_filesystem *fs, struct spdk_io_channel *channel, |
224 | const char *name); | |
225 | ||
11fdf7f2 TL |
226 | /** |
227 | * Open the file. | |
228 | * | |
229 | * \param fs Blobstore filesystem. | |
230 | * \param channel The I/O channel used to allocate file request. | |
231 | * \param name The file name used to look up the matched file in the blobstore filesystem. | |
232 | * \param flags This flags will be used to control the open mode. | |
233 | * \param file It will point to the open file if sccessful or NULL otherwirse. | |
234 | * | |
235 | * \return 0 on success, negative errno on failure. | |
236 | */ | |
7c673cae FG |
237 | int spdk_fs_open_file(struct spdk_filesystem *fs, struct spdk_io_channel *channel, |
238 | const char *name, uint32_t flags, struct spdk_file **file); | |
239 | ||
11fdf7f2 TL |
240 | /** |
241 | * Close the file. | |
242 | * | |
243 | * \param file File to close. | |
244 | * \param channel The I/O channel used to allocate file request. | |
245 | * | |
246 | * \return 0 on success, negative errno on failure. | |
247 | */ | |
7c673cae FG |
248 | int spdk_file_close(struct spdk_file *file, struct spdk_io_channel *channel); |
249 | ||
11fdf7f2 TL |
250 | /** |
251 | * Change the file name. | |
252 | * | |
253 | * This operation will overwrite an existing file if there is a file with the | |
254 | * same name. | |
255 | * | |
256 | * \param fs Blobstore filesystem. | |
257 | * \param channel The I/O channel used to allocate file request. | |
258 | * \param old_name Old name of the file. | |
259 | * \param new_name New name of the file. | |
260 | * | |
261 | * \return 0 on success, negative errno on failure. | |
262 | */ | |
7c673cae FG |
263 | int spdk_fs_rename_file(struct spdk_filesystem *fs, struct spdk_io_channel *channel, |
264 | const char *old_name, const char *new_name); | |
265 | ||
11fdf7f2 TL |
266 | /** |
267 | * Delete the file. | |
268 | * | |
269 | * \param fs Blobstore filesystem. | |
270 | * \param channel The I/O channel used to allocate file request. | |
271 | * \param name The name of the file to be deleted. | |
272 | * | |
273 | * \return 0 on success, negative errno on failure. | |
274 | */ | |
7c673cae FG |
275 | int spdk_fs_delete_file(struct spdk_filesystem *fs, struct spdk_io_channel *channel, |
276 | const char *name); | |
277 | ||
11fdf7f2 TL |
278 | /** |
279 | * Get the first file in the blobstore filesystem. | |
280 | * | |
281 | * \param fs Blobstore filesystem to traverse. | |
282 | * | |
283 | * \return an iterator which points to the first file in the blobstore filesystem. | |
284 | */ | |
7c673cae | 285 | spdk_fs_iter spdk_fs_iter_first(struct spdk_filesystem *fs); |
11fdf7f2 TL |
286 | |
287 | /** | |
288 | * Get the next file in the blobstore filesystem by using the input iterator. | |
289 | * | |
290 | * \param iter The iterator which points to the current file struct. | |
291 | * | |
292 | * \return an iterator which points to the next file in the blobstore filesystem. | |
293 | */ | |
7c673cae | 294 | spdk_fs_iter spdk_fs_iter_next(spdk_fs_iter iter); |
11fdf7f2 | 295 | |
7c673cae FG |
296 | #define spdk_fs_iter_get_file(iter) ((struct spdk_file *)(iter)) |
297 | ||
11fdf7f2 TL |
298 | /** |
299 | * Truncate the file. | |
300 | * | |
301 | * \param file File to truncate. | |
302 | * \param channel The I/O channel used to allocate file request. | |
303 | * \param length New size in bytes of the file. | |
304 | * | |
305 | * \return 0 on success, negative errno on failure. | |
306 | */ | |
307 | int spdk_file_truncate(struct spdk_file *file, struct spdk_io_channel *channel, | |
308 | uint64_t length); | |
7c673cae | 309 | |
11fdf7f2 TL |
310 | /** |
311 | * Get file name. | |
312 | * | |
313 | * \param file File to query. | |
314 | * | |
315 | * \return the name of the file. | |
316 | */ | |
7c673cae FG |
317 | const char *spdk_file_get_name(struct spdk_file *file); |
318 | ||
11fdf7f2 TL |
319 | /** |
320 | * Obtain the size of the file. | |
321 | * | |
322 | * \param file File to query. | |
323 | * | |
324 | * \return the size in bytes of the file. | |
325 | */ | |
7c673cae FG |
326 | uint64_t spdk_file_get_length(struct spdk_file *file); |
327 | ||
11fdf7f2 TL |
328 | /** |
329 | * Write data to the given file. | |
330 | * | |
331 | * \param file File to write. | |
332 | * \param channel The I/O channel used to allocate file request. | |
333 | * \param payload The specified buffer which should contain the data to be transmitted. | |
334 | * \param offset The beginning position to write data. | |
335 | * \param length The size in bytes of data to write. | |
336 | * | |
337 | * \return 0 on success, negative errno on failure. | |
338 | */ | |
7c673cae FG |
339 | int spdk_file_write(struct spdk_file *file, struct spdk_io_channel *channel, |
340 | void *payload, uint64_t offset, uint64_t length); | |
341 | ||
11fdf7f2 TL |
342 | /** |
343 | * Read data to user buffer from the given file. | |
344 | * | |
345 | * \param file File to read. | |
346 | * \param channel The I/O channel used to allocate file request. | |
347 | * \param payload The specified buffer which will store the obtained data. | |
348 | * \param offset The beginning position to read. | |
349 | * \param length The size in bytes of data to read. | |
350 | * | |
351 | * \return the end position of this read operation on success, negated errno on failure. | |
352 | */ | |
7c673cae FG |
353 | int64_t spdk_file_read(struct spdk_file *file, struct spdk_io_channel *channel, |
354 | void *payload, uint64_t offset, uint64_t length); | |
355 | ||
11fdf7f2 TL |
356 | /** |
357 | * Set cache size for the blobstore filesystem. | |
358 | * | |
359 | * \param size_in_mb Cache size in megabytes. | |
360 | */ | |
7c673cae | 361 | void spdk_fs_set_cache_size(uint64_t size_in_mb); |
11fdf7f2 TL |
362 | |
363 | /** | |
364 | * Obtain the cache size. | |
365 | * | |
366 | * \return cache size in megabytes. | |
367 | */ | |
7c673cae FG |
368 | uint64_t spdk_fs_get_cache_size(void); |
369 | ||
370 | #define SPDK_FILE_PRIORITY_LOW 0 /* default */ | |
371 | #define SPDK_FILE_PRIORITY_HIGH 1 | |
372 | ||
11fdf7f2 TL |
373 | /** |
374 | * Set priority for the file. | |
375 | * | |
376 | * \param file File to set priority. | |
377 | * \param priority Priority level (SPDK_FILE_PRIORITY_LOW or SPDK_FILE_PRIORITY_HIGH). | |
378 | */ | |
7c673cae FG |
379 | void spdk_file_set_priority(struct spdk_file *file, uint32_t priority); |
380 | ||
11fdf7f2 TL |
381 | /** |
382 | * Synchronize the data from the cache to the disk. | |
383 | * | |
384 | * \param file File to sync. | |
385 | * \param channel The I/O channel used to allocate file request. | |
386 | * | |
387 | * \return 0 on success. | |
388 | */ | |
7c673cae FG |
389 | int spdk_file_sync(struct spdk_file *file, struct spdk_io_channel *channel); |
390 | ||
11fdf7f2 TL |
391 | /** |
392 | * Get the unique ID for the file. | |
393 | * | |
394 | * \param file File to get the ID. | |
395 | * \param id ID buffer. | |
396 | * \param size Size of the ID buffer. | |
397 | * | |
398 | * \return the length of ID on success. | |
399 | */ | |
400 | int spdk_file_get_id(struct spdk_file *file, void *id, size_t size); | |
401 | ||
402 | #ifdef __cplusplus | |
403 | } | |
404 | #endif | |
405 | ||
7c673cae | 406 | #endif /* SPDK_FS_H_ */ |