Line data Source code
1 : /*
2 : * Copyright(c) 2012-2022 Intel Corporation
3 : * SPDX-License-Identifier: BSD-3-Clause
4 : */
5 :
6 : #ifndef __OCF_MNGT_H__
7 : #define __OCF_MNGT_H__
8 :
9 : #include "ocf_cache.h"
10 : #include "ocf_core.h"
11 :
12 : /**
13 : * @file
14 : * @brief OCF management operations definitions
15 : */
16 :
17 : /**
18 : * @brief Core start configuration
19 : */
20 : struct ocf_mngt_core_config {
21 : /**
22 : * @brief OCF core name
23 : */
24 : char name[OCF_CORE_NAME_SIZE];
25 :
26 : /**
27 : * @brief OCF core volume UUID
28 : */
29 : struct ocf_volume_uuid uuid;
30 :
31 : /**
32 : * @brief OCF core volume type
33 : */
34 : uint8_t volume_type;
35 :
36 : /**
37 : * @brief Add core to pool if cache isn't present or add core to
38 : * earlier loaded cache
39 : */
40 : bool try_add;
41 :
42 : uint32_t seq_cutoff_threshold;
43 : /*!< Sequential cutoff threshold (in bytes) */
44 :
45 : uint32_t seq_cutoff_promotion_count;
46 : /*!< Sequential cutoff promotion request count */
47 :
48 : bool seq_cutoff_promote_on_threshold;
49 : /*!< Sequential cutoff promote on threshold */
50 :
51 : struct {
52 : void *data;
53 : size_t size;
54 : } user_metadata;
55 : };
56 :
57 : /**
58 : * @brief Initialize core config to default values
59 : *
60 : * @note This function doesn't initialize name, uuid and volume_type fields
61 : * which have no default values and are required to be set by user.
62 : *
63 : * @param[in] cfg Core config stucture
64 : */
65 0 : static inline void ocf_mngt_core_config_set_default(
66 : struct ocf_mngt_core_config *cfg)
67 : {
68 0 : cfg->try_add = false;
69 0 : cfg->seq_cutoff_threshold = 1024;
70 0 : cfg->seq_cutoff_promotion_count = 8;
71 0 : cfg->seq_cutoff_promote_on_threshold = false;
72 0 : cfg->user_metadata.data = NULL;
73 0 : cfg->user_metadata.size = 0;
74 0 : }
75 :
76 : /**
77 : * @brief Get number of OCF caches
78 : *
79 : * @param[in] ctx OCF context
80 : *
81 : * @retval Number of caches in given OCF instance
82 : */
83 : uint32_t ocf_mngt_cache_get_count(ocf_ctx_t ctx);
84 :
85 : /* Cache instances getters */
86 :
87 : /**
88 : * @brief Get OCF cache by name
89 : *
90 : * @note This function on success also increases reference counter
91 : * in given cache
92 : *
93 : * @param[in] ctx OCF context
94 : * @param[in] name OCF cache name
95 : * @param[in] name_len Cache name length
96 : * @param[out] cache OCF cache handle
97 : *
98 : * @retval 0 Get cache successfully
99 : * @retval -OCF_ERR_CACHE_NOT_EXIST Cache with given name doesn't exist
100 : */
101 : int ocf_mngt_cache_get_by_name(ocf_ctx_t ctx, const char* name, size_t name_len,
102 : ocf_cache_t *cache);
103 :
104 : /**
105 : * @brief Increment reference counter of cache
106 : *
107 : * @param[in] cache OCF cache handle
108 : *
109 : * @retval 0 Reference counter incremented
110 : * @retval -OCF_ERR_CACHE_NOT_AVAIL cache isn't initialised yet
111 : */
112 : int ocf_mngt_cache_get(ocf_cache_t cache);
113 :
114 : /**
115 : * @brief Decrease reference counter in cache
116 : *
117 : * @note If cache don't have any reference - deallocate it
118 : *
119 : * @param[in] cache Handle to cache
120 : */
121 : void ocf_mngt_cache_put(ocf_cache_t cache);
122 :
123 : /**
124 : * @brief Lock cache for management oparations (write lock, exclusive)
125 :
126 : * @param[in] cache Handle to cache
127 : * @param[in] error Status error code. Can be one of the following:
128 : * 0 Cache successfully locked
129 : * -OCF_ERR_CACHE_NOT_EXIST Can not lock cache - cache is already stopping
130 : * -OCF_ERR_NO_MEM Cannot allocate needed memory
131 : * -OCF_ERR_INTR Wait operation interrupted
132 : */
133 : typedef void (*ocf_mngt_cache_lock_end_t)(ocf_cache_t cache,
134 : void *priv, int error);
135 :
136 : /**
137 : * @brief Lock cache for management oparations (write lock, exclusive)
138 : *
139 : * @param[in] cache Handle to cache
140 : * @param[in] cmpl Completion callback
141 : * @param[in] priv Private context of completion callback
142 : */
143 : void ocf_mngt_cache_lock(ocf_cache_t cache,
144 : ocf_mngt_cache_lock_end_t cmpl, void *priv);
145 :
146 : /**
147 : * @brief Lock cache for read - assures cache config does not change while
148 : * lock is being held, while allowing other users to acquire
149 : * read lock in parallel.
150 : *
151 : * @param[in] cache Handle to cache
152 : * @param[in] cmpl Completion callback
153 : * @param[in] priv Private context of completion callback
154 : */
155 : void ocf_mngt_cache_read_lock(ocf_cache_t cache,
156 : ocf_mngt_cache_lock_end_t cmpl, void *priv);
157 :
158 : /**
159 : * @brief Lock cache for management oparations (write lock, exclusive)
160 : *
161 : * @param[in] cache Handle to cache
162 : *
163 : * @retval 0 Cache successfully locked
164 : * @retval -OCF_ERR_CACHE_NOT_EXIST Can not lock cache - cache is already
165 : * stopping
166 : * @retval -OCF_ERR_NO_LOCK Lock not acquired
167 : */
168 : int ocf_mngt_cache_trylock(ocf_cache_t cache);
169 :
170 : /**
171 : * @brief Lock cache for read - assures cache config does not change while
172 : * lock is being held, while allowing other users to acquire
173 : * read lock in parallel.
174 : *
175 : * @param[in] cache Handle to cache
176 : *
177 : * @retval 0 Cache successfully locked
178 : * @retval -OCF_ERR_CACHE_NOT_EXIST Can not lock cache - cache is already
179 : * stopping
180 : * @retval -OCF_ERR_NO_LOCK Lock not acquired
181 : */
182 : int ocf_mngt_cache_read_trylock(ocf_cache_t cache);
183 :
184 : /**
185 : * @brief Write-unlock cache
186 : *
187 : * @param[in] cache Handle to cache
188 : */
189 : void ocf_mngt_cache_unlock(ocf_cache_t cache);
190 :
191 : /**
192 : * @brief Read-unlock cache
193 : *
194 : * @param[in] cache Handle to cache
195 : */
196 : void ocf_mngt_cache_read_unlock(ocf_cache_t cache);
197 :
198 : /**
199 : * @brief Cache visitor function
200 : *
201 : * @param[in] cache Handle to cache
202 : * @param[in] cntx Visitor function context
203 : *
204 : * @retval 0 Success
205 : * @retval Non-zero Error
206 : */
207 : typedef int (*ocf_mngt_cache_visitor_t)(ocf_cache_t cache, void *cntx);
208 :
209 : /**
210 : * @brief Loop for each cache
211 : *
212 : * @note Visitor function is called for each cache
213 : *
214 : * @param[in] ctx OCF context
215 : * @param[in] visitor OCF cache visitor function
216 : * @param[in] cntx Context for cache visitor function
217 : *
218 : * @retval 0 Success
219 : * @retval Non-zero Error
220 : */
221 : int ocf_mngt_cache_visit(ocf_ctx_t ctx, ocf_mngt_cache_visitor_t visitor,
222 : void *cntx);
223 :
224 : /**
225 : * @brief Loop for each cache reverse
226 : *
227 : * @note Visitor function is called for each cache
228 : *
229 : * @param[in] ctx OCF context
230 : * @param[in] visitor OCF cache visitor function
231 : * @param[in] cntx Context for cache visitor function
232 : *
233 : * @retval 0 Success
234 : * @retval Non-zero Error
235 : */
236 : int ocf_mngt_cache_visit_reverse(ocf_ctx_t ctx, ocf_mngt_cache_visitor_t visitor,
237 : void *cntx);
238 :
239 : /**
240 : * @brief Cache start configuration
241 : */
242 : struct ocf_mngt_cache_config {
243 : /**
244 : * @brief Cache name
245 : */
246 : char name[OCF_CACHE_NAME_SIZE];
247 :
248 : /**
249 : * @brief Cache mode
250 : */
251 : ocf_cache_mode_t cache_mode;
252 :
253 : /**
254 : * @brief Promotion policy type
255 : */
256 : ocf_promotion_t promotion_policy;
257 :
258 : /**
259 : * @brief Cache line size
260 : */
261 : ocf_cache_line_size_t cache_line_size;
262 :
263 : bool metadata_volatile;
264 :
265 : /**
266 : * @brief Start cache and keep it locked
267 : *
268 : * @note In this case caller is able to perform additional activities
269 : * and then shall unlock cache
270 : */
271 : bool locked;
272 :
273 : /**
274 : * @brief Use pass-through mode for I/O requests unaligned to 4KiB
275 : */
276 : bool pt_unaligned_io;
277 :
278 : /**
279 : * @brief If set, try to submit all I/O in fast path.
280 : */
281 : bool use_submit_io_fast;
282 :
283 : /**
284 : * @brief Backfill configuration
285 : */
286 : struct {
287 : uint32_t max_queue_size;
288 : uint32_t queue_unblock_size;
289 : } backfill;
290 : };
291 :
292 : /**
293 : * @brief Initialize core config to default values
294 : *
295 : * @note This function doesn't initialize name field which has no default
296 : * value and is required to be set by user.
297 : *
298 : * @param[in] cfg Cache config stucture
299 : */
300 0 : static inline void ocf_mngt_cache_config_set_default(
301 : struct ocf_mngt_cache_config *cfg)
302 : {
303 0 : cfg->cache_mode = ocf_cache_mode_default;
304 0 : cfg->promotion_policy = ocf_promotion_default;
305 0 : cfg->cache_line_size = ocf_cache_line_size_4;
306 0 : cfg->metadata_volatile = false;
307 0 : cfg->backfill.max_queue_size = 65536;
308 0 : cfg->backfill.queue_unblock_size = 60000;
309 0 : cfg->locked = false;
310 0 : cfg->pt_unaligned_io = false;
311 0 : cfg->use_submit_io_fast = false;
312 0 : }
313 :
314 : /**
315 : * @brief Start cache instance
316 : *
317 : * @param[in] ctx OCF context
318 : * @param[out] cache Cache handle
319 : * @param[in] cfg Starting cache configuration
320 : * @param[in] priv initial value of priv field in cache
321 : *
322 : * @retval 0 Cache started successfully
323 : * @retval Non-zero Error occurred and starting cache failed
324 : */
325 : int ocf_mngt_cache_start(ocf_ctx_t ctx, ocf_cache_t *cache,
326 : struct ocf_mngt_cache_config *cfg, void *priv);
327 :
328 : /**
329 : * @brief Set queue to be used during management operations
330 : *
331 : * @param[in] cache Cache object
332 : * @param[in] queue Queue object
333 : *
334 : * @retval 0 Success
335 : * @retval Non-zero Error occurred
336 : */
337 : int ocf_mngt_cache_set_mngt_queue(ocf_cache_t cache, ocf_queue_t queue);
338 :
339 : /**
340 : * @brief Completion callback of cache stop operation
341 : *
342 : * @param[in] cache Cache handle
343 : * @param[in] priv Callback context
344 : * @param[in] error Error code (zero on success)
345 : */
346 : typedef void (*ocf_mngt_cache_stop_end_t)(ocf_cache_t cache,
347 : void *priv, int error);
348 :
349 : /**
350 : * @brief Stop cache instance
351 : *
352 : * @param[in] cache Cache handle
353 : * @param[in] cmpl Completion callback
354 : * @param[in] priv Completion callback context
355 : */
356 : void ocf_mngt_cache_stop(ocf_cache_t cache,
357 : ocf_mngt_cache_stop_end_t cmpl, void *priv);
358 :
359 : /**
360 : * @brief Caching device configuration
361 : */
362 : struct ocf_mngt_cache_device_config {
363 : /**
364 : * @brief Cache volume
365 : *
366 : * The volume ownership is moved to the context of operation that takes
367 : * this config. Thus the volume is being effectively moved using
368 : * ocf_volume_move(), leaving the original volume uninitialized.
369 : *
370 : * Note that if the original volume was instantiated using *_create
371 : * function, it still needs to be destroyed using ocf_volume_destroy()
372 : * to deallocate the memory.
373 : */
374 : ocf_volume_t volume;
375 :
376 : /**
377 : * @brief If set, cache features (like discard) are tested
378 : * before starting cache
379 : */
380 : bool perform_test;
381 :
382 : /**
383 : * @brief Optional opaque volume parameters, passed down to cache volume
384 : * open callback
385 : */
386 : void *volume_params;
387 : };
388 :
389 : /**
390 : * @brief Cache attach configuration
391 : */
392 : struct ocf_mngt_cache_attach_config {
393 : /**
394 : * @brief Cache device configuration - must be the first field
395 : */
396 : struct ocf_mngt_cache_device_config device;
397 :
398 : /**
399 : * @brief Cache line size
400 : */
401 : ocf_cache_line_size_t cache_line_size;
402 :
403 : /**
404 : * @brief Automatically open core volumes when loading cache
405 : *
406 : * If set to false, cache load will not attempt to open core volumes,
407 : * and so cores will be marked "inactive" unless their volumes were
408 : * earlier added to the core pool. In such case user will be expected
409 : * to add cores later using function ocf_mngt_cache_add_core().
410 : *
411 : * @note This option is meaningful only with ocf_mngt_cache_load().
412 : * When used with ocf_mngt_cache_attach() it's ignored.
413 : */
414 : bool open_cores;
415 :
416 : /**
417 : * @brief Ignore warnings and initialize new cache instance
418 : *
419 : * If set to true, it will force initializing new cache despite the
420 : * existing metadata from previous cache instance.
421 : *
422 : * @note This flag is not allowed when loading existing cache instance.
423 : */
424 : bool force;
425 :
426 : /**
427 : * @brief If set, cache device will be discarded on cache start
428 : */
429 : bool discard_on_start;
430 :
431 : /**
432 : * @brief If set, asynchronous cleaning will be disabled
433 : *
434 : * Has similar effect to setting cleaning policy to NOP, but
435 : * additionally prevents allocating "cleaning" metadata section,
436 : * which can reduce memory footprint by up to 20%.
437 : *
438 : * When this option is selected, any attempt to change the cleaning
439 : * policy will fail.
440 : *
441 : * @note This option is meaningful only with ocf_mngt_cache_attach().
442 : * When used with ocf_mngt_cache_load() it's ignored.
443 : */
444 : bool disable_cleaner;
445 : };
446 :
447 : /**
448 : * @brief Initialize core config to default values
449 : *
450 : * @note This function doesn't initiialize uuid and volume_type fields
451 : * which have no default values and are required to be set by user.
452 : *
453 : * @param[in] cfg Cache device config stucture
454 : */
455 0 : static inline void ocf_mngt_cache_attach_config_set_default(
456 : struct ocf_mngt_cache_attach_config *cfg)
457 : {
458 0 : cfg->cache_line_size = ocf_cache_line_size_none;
459 0 : cfg->open_cores = true;
460 0 : cfg->force = false;
461 0 : cfg->discard_on_start = true;
462 0 : cfg->disable_cleaner = false;
463 0 : cfg->device.perform_test = true;
464 0 : cfg->device.volume_params = NULL;
465 0 : }
466 :
467 : /**
468 : * @brief Get amount of free RAM needed to attach cache volume
469 : *
470 : * @param[in] cache Cache handle
471 : * @param[in] cfg Caching device configuration
472 : * @param[out] ram_needed Amount of RAM needed in bytes
473 : *
474 : * @retval 0 Success
475 : * @retval Non-zero Error occurred
476 : */
477 : int ocf_mngt_get_ram_needed(ocf_cache_t cache,
478 : struct ocf_mngt_cache_device_config *cfg, uint64_t *ram_needed);
479 :
480 : /**
481 : * @brief Completion callback of cache attach operation
482 : *
483 : * @param[in] cache Cache handle
484 : * @param[in] priv Callback context
485 : * @param[in] error Error code (zero on success)
486 : */
487 : typedef void (*ocf_mngt_cache_attach_end_t)(ocf_cache_t cache,
488 : void *priv, int error);
489 :
490 : /**
491 : * @brief Attach caching device to cache instance
492 : *
493 : * @param[in] cache Cache handle
494 : * @param[in] cfg Caching device configuration
495 : * @param[in] cmpl Completion callback
496 : * @param[in] priv Completion callback context
497 : */
498 : void ocf_mngt_cache_attach(ocf_cache_t cache,
499 : struct ocf_mngt_cache_attach_config *cfg,
500 : ocf_mngt_cache_attach_end_t cmpl, void *priv);
501 :
502 : /**
503 : * @brief Completion callback of cache detach operation
504 : *
505 : * @param[in] cache Cache handle
506 : * @param[in] priv Callback context
507 : * @param[in] error Error code (zero on success)
508 : */
509 : typedef void (*ocf_mngt_cache_detach_end_t)(ocf_cache_t cache,
510 : void *priv, int error);
511 :
512 : /**
513 : * @brief Detach caching cache
514 : *
515 : * @param[in] cache Cache handle
516 : * @param[in] cmpl Completion callback
517 : * @param[in] priv Completion callback context
518 : */
519 : void ocf_mngt_cache_detach(ocf_cache_t cache,
520 : ocf_mngt_cache_detach_end_t cmpl, void *priv);
521 :
522 : /**
523 : * @brief Completion callback of cache load operation
524 : *
525 : * @param[in] cache Cache handle
526 : * @param[in] priv Callback context
527 : * @param[in] error Error code (zero on success)
528 : */
529 : typedef void (*ocf_mngt_cache_load_end_t)(ocf_cache_t cache,
530 : void *priv, int error);
531 :
532 : /**
533 : * @brief Load cache instance
534 : *
535 : * @param[in] cache Cache handle
536 : * @param[in] cfg Caching device configuration
537 : * @param[in] cmpl Completion callback
538 : * @param[in] priv Completion callback context
539 : */
540 : void ocf_mngt_cache_load(ocf_cache_t cache,
541 : struct ocf_mngt_cache_attach_config *cfg,
542 : ocf_mngt_cache_load_end_t cmpl, void *priv);
543 :
544 : /**
545 : * @brief Completion callback of cache standby attach operation
546 : *
547 : * @param[in] cache Cache handle
548 : * @param[in] priv Callback context
549 : * @param[in] error Error code (zero on success)
550 : */
551 : typedef void (*ocf_mngt_cache_standby_attach_end_t)(ocf_cache_t cache,
552 : void *priv, int error);
553 :
554 : /**
555 : * @brief Attach caching device to cache instance in failover standby mode
556 : *
557 : * @param[in] cache Cache handle
558 : * @param[in] cfg Caching device configuration
559 : * @param[in] cmpl Completion callback
560 : * @param[in] priv Completion callback context
561 : */
562 : void ocf_mngt_cache_standby_attach(ocf_cache_t cache,
563 : struct ocf_mngt_cache_attach_config *cfg,
564 : ocf_mngt_cache_standby_attach_end_t cmpl, void *priv);
565 :
566 : /**
567 : * @brief Completion callback of cache standby load operation
568 : *
569 : * @param[in] cache Cache handle
570 : * @param[in] priv Callback context
571 : * @param[in] error Error code (zero on success)
572 : */
573 : typedef void (*ocf_mngt_cache_standby_load_end_t)(ocf_cache_t cache,
574 : void *priv, int error);
575 : /**
576 : * @brief Load cache instance in failover standby mode
577 : *
578 : * @param[in] cache Cache handle
579 : * @param[in] cfg Caching device configuration
580 : * @param[in] cmpl Completion callback
581 : * @param[in] priv Completion callback context
582 : */
583 : void ocf_mngt_cache_standby_load(ocf_cache_t cache,
584 : struct ocf_mngt_cache_attach_config *cfg,
585 : ocf_mngt_cache_standby_load_end_t cmpl, void *priv);
586 :
587 : /**
588 : * @brief Completion callback of cache standby detach operation
589 : *
590 : * @param[in] cache Cache handle
591 : * @param[in] priv Callback context
592 : * @param[in] error Error code (zero on success)
593 : */
594 : typedef void (*ocf_mngt_cache_standby_detach_end_t)(void *priv, int error);
595 :
596 : /**
597 : * @brief Detach cache volume from cache in standby mode
598 : *
599 : * @param[in] cache Cache handle
600 : * @param[in] cmpl Completion callback
601 : * @param[in] priv Completion callback context
602 : */
603 : void ocf_mngt_cache_standby_detach(ocf_cache_t cache,
604 : ocf_mngt_cache_standby_detach_end_t cmpl, void *priv);
605 :
606 : /**
607 : * @brief Cache standby activate configuration
608 : */
609 : struct ocf_mngt_cache_standby_activate_config {
610 : /**
611 : * @brief Cache device configuration - must be the first field
612 : */
613 : struct ocf_mngt_cache_device_config device;
614 :
615 : /**
616 : * @brief Automatically open core volumes when activating cache
617 : *
618 : * If set to false, cache load will not attempt to open core volumes,
619 : * and so cores will be marked "inactive" unless their volumes were
620 : * earlier added to the core pool. In such case user will be expected
621 : * to add cores later using function ocf_mngt_cache_add_core().
622 : */
623 : bool open_cores;
624 : };
625 :
626 : /**
627 : * @brief Completion callback of standby cache activate operation
628 : *
629 : * @param[in] cache Cache handle
630 : * @param[in] priv Callback context
631 : * @param[in] error Error code (zero on success)
632 : */
633 : typedef void (*ocf_mngt_cache_standby_activate_end_t)(ocf_cache_t cache,
634 : void *priv, int error);
635 :
636 : /**
637 : * @brief Activate standby cache instance
638 : *
639 : * @param[in] cache Cache handle
640 : * @param[in] cfg Caching device configuration
641 : * @param[in] cmpl Completion callback
642 : * @param[in] priv Completion callback context
643 : */
644 : void ocf_mngt_cache_standby_activate(ocf_cache_t cache,
645 : struct ocf_mngt_cache_standby_activate_config *cfg,
646 : ocf_mngt_cache_standby_activate_end_t cmpl, void *priv);
647 :
648 : /* Adding and removing cores */
649 :
650 : /**
651 : * @brief Completion callback of add core operation
652 : *
653 : * @param[in] cache Cache handle
654 : * @param[in] core Core handle on success or NULL on failure
655 : * @param[in] priv Callback context
656 : * @param[in] error Error code (zero on success)
657 : */
658 : typedef void (*ocf_mngt_cache_add_core_end_t)(ocf_cache_t cache,
659 : ocf_core_t core, void *priv, int error);
660 :
661 : /**
662 : * @brief Add core to cache instance
663 : *
664 : * @param[in] cache Cache handle
665 : * @param[in] cfg Core configuration
666 : * @param[in] cmpl Completion callback
667 : * @param[in] priv Completion callback context
668 : */
669 : void ocf_mngt_cache_add_core(ocf_cache_t cache,
670 : struct ocf_mngt_core_config *cfg,
671 : ocf_mngt_cache_add_core_end_t cmpl, void *priv);
672 :
673 : /**
674 : * @brief Completion callback of remove core operation
675 : *
676 : * @param[in] priv Callback context
677 : * @param[in] error Error code (zero on success)
678 : */
679 : typedef void (*ocf_mngt_cache_remove_core_end_t)(void *priv, int error);
680 :
681 : /**
682 : * @brief Remove core from cache instance
683 : *
684 : * @param[in] core Core handle
685 : * @param[in] cmpl Completion callback
686 : * @param[in] priv Completion callback context
687 : */
688 : void ocf_mngt_cache_remove_core(ocf_core_t core,
689 : ocf_mngt_cache_remove_core_end_t cmpl, void *priv);
690 :
691 : /**
692 : * @brief Completion callback of detach core operation
693 : *
694 : * @param[in] priv Callback context
695 : * @param[in] error Error code (zero on success)
696 : */
697 : typedef void (*ocf_mngt_cache_detach_core_end_t)(void *priv, int error);
698 :
699 : /**
700 : * @brief Detach core from cache instance
701 : *
702 : * @param[in] core Core handle
703 : * @param[in] cmpl Completion callback
704 : * @param[in] priv Completion callback context
705 : */
706 : void ocf_mngt_cache_detach_core(ocf_core_t core,
707 : ocf_mngt_cache_detach_core_end_t cmpl, void *priv);
708 :
709 : /* Flush operations */
710 :
711 : /**
712 : * @brief Completion callback of cache flush operation
713 : *
714 : * @param[in] cache Cache handle
715 : * @param[in] priv Callback context
716 : * @param[in] error Error code (zero on success)
717 : */
718 : typedef void (*ocf_mngt_cache_flush_end_t)(ocf_cache_t cache,
719 : void *priv, int error);
720 :
721 : /**
722 : * @brief Flush data from given cache
723 : *
724 : * @param[in] cache Cache handle
725 : * @param[in] cmpl Completion callback
726 : * @param[in] priv Completion callback context
727 : */
728 : void ocf_mngt_cache_flush(ocf_cache_t cache,
729 : ocf_mngt_cache_flush_end_t cmpl, void *priv);
730 :
731 : /**
732 : * @brief Check if core is dirty
733 : *
734 : * @param[in] core Core handle
735 : *
736 : * @retval true if core is dirty, false otherwise
737 : */
738 : bool ocf_mngt_core_is_dirty(ocf_core_t core);
739 :
740 : /**
741 : * @brief Check if cache is dirty
742 : *
743 : * @param[in] cache Cache handle
744 : *
745 : * @retval true if cache is dirty, false otherwise
746 : */
747 : bool ocf_mngt_cache_is_dirty(ocf_cache_t cache);
748 :
749 : /**
750 : * @brief Completion callback of core flush operation
751 : *
752 : * @param[in] core Core handle
753 : * @param[in] priv Callback context
754 : * @param[in] error Error code (zero on success)
755 : */
756 : typedef void (*ocf_mngt_core_flush_end_t)(ocf_core_t core,
757 : void *priv, int error);
758 :
759 : /**
760 : * @brief Flush data to given core
761 : *
762 : * @param[in] core Core handle
763 : * @param[in] cmpl Completion callback
764 : * @param[in] priv Completion callback context
765 : */
766 : void ocf_mngt_core_flush(ocf_core_t core,
767 : ocf_mngt_core_flush_end_t cmpl, void *priv);
768 :
769 : /**
770 : * @brief Completion callback of cache purge operation
771 : *
772 : * @param[in] cache Cache handle
773 : * @param[in] priv Callback context
774 : * @param[in] error Error code (zero on success)
775 : */
776 : typedef void (*ocf_mngt_cache_purge_end_t)(ocf_cache_t cache,
777 : void *priv, int error);
778 :
779 : /**
780 : * @brief Purge data from given cache
781 : *
782 : * @param[in] cache Cache handle
783 : * @param[in] cmpl Completion callback
784 : * @param[in] priv Completion callback context
785 : */
786 : void ocf_mngt_cache_purge(ocf_cache_t cache,
787 : ocf_mngt_cache_purge_end_t cmpl, void *priv);
788 :
789 : /**
790 : * @brief Completion callback of core purge operation
791 : *
792 : * @param[in] core Core handle
793 : * @param[in] priv Callback context
794 : * @param[in] error Error code (zero on success)
795 : */
796 : typedef void (*ocf_mngt_core_purge_end_t)(ocf_core_t core,
797 : void *priv, int error);
798 :
799 : /**
800 : * @brief Purge data to given core
801 : *
802 : * @param[in] core Core handle
803 : * @param[in] cmpl Completion callback
804 : * @param[in] priv Completion callback context
805 : */
806 : void ocf_mngt_core_purge(ocf_core_t core,
807 : ocf_mngt_core_purge_end_t cmpl, void *priv);
808 :
809 : /**
810 : * @brief Interrupt existing flushing of cache or core
811 : *
812 : * @param[in] cache Cache instance
813 : */
814 : void ocf_mngt_cache_flush_interrupt(ocf_cache_t cache);
815 :
816 : /**
817 : * @brief Completion callback of save operation
818 : *
819 : * @param[in] cache Cache handle
820 : * @param[in] priv Callback context
821 : * @param[in] error Error code (zero on success)
822 : */
823 : typedef void (*ocf_mngt_cache_save_end_t)(ocf_cache_t cache,
824 : void *priv, int error);
825 :
826 : /**
827 : * @brief Save cache configuration data on cache volume
828 : *
829 : * This function should be called after changing cache or core parameters
830 : * in order to make changes persistent.
831 : *
832 : * @param[in] cache Cache handle
833 : * @param[in] cmpl Completion callback
834 : * @param[in] priv Completion callback context
835 : */
836 : void ocf_mngt_cache_save(ocf_cache_t cache,
837 : ocf_mngt_cache_save_end_t cmpl, void *priv);
838 :
839 : /**
840 : * @brief Determines whether given cache mode has write-back semantics, i.e. it
841 : * allows for writes to be serviced in cache and lazily propagated to core.
842 : *
843 : * @param[in] mode input cache mode
844 : */
845 : static inline bool ocf_mngt_cache_mode_has_lazy_write(ocf_cache_mode_t mode)
846 : {
847 : return mode == ocf_cache_mode_wb || mode == ocf_cache_mode_wo;
848 : }
849 :
850 : /**
851 : * @brief Set cache mode in given cache
852 : *
853 : * @attention This changes only runtime state. To make changes persistent
854 : * use function ocf_mngt_cache_save().
855 : *
856 : * @param[in] cache Cache handle
857 : * @param[in] mode Cache mode to set
858 : *
859 : * @retval 0 Cache mode have been set successfully
860 : * @retval Non-zero Error occurred and cache mode not been set
861 : */
862 : int ocf_mngt_cache_set_mode(ocf_cache_t cache, ocf_cache_mode_t mode);
863 :
864 : /**
865 : * @brief Completion callback of switch cleaning policy operation
866 : *
867 : * @param[in] priv Callback context
868 : * @param[in] error Error code (zero on success)
869 : */
870 : typedef void (*ocf_mngt_cache_set_cleaning_policy_end_t)( void *priv,
871 : int error);
872 :
873 : /**
874 : * @brief Set cleaning policy in given cache
875 : *
876 : * @attention This changes only runtime state. To make changes persistent
877 : * use function ocf_mngt_cache_save().
878 : *
879 : * @param[in] cache Cache handle
880 : * @param[out] new_policy New cleaning policy
881 : * @param[in] cmpl Completion callback
882 : * @param[in] priv Completion callback context
883 : *
884 : */
885 : void ocf_mngt_cache_cleaning_set_policy(ocf_cache_t cache,
886 : ocf_cleaning_t new_policy,
887 : ocf_mngt_cache_set_cleaning_policy_end_t cmpl, void *priv);
888 :
889 : /**
890 : * @brief Get current cleaning policy from given cache
891 : *
892 : * @param[in] cache Cache handle
893 : * @param[out] type Variable to store current cleaning policy type
894 : *
895 : * @retval 0 Policy has been get successfully
896 : * @retval Non-zero Error occurred and policy has not been get
897 : */
898 : int ocf_mngt_cache_cleaning_get_policy(ocf_cache_t cache, ocf_cleaning_t *type);
899 :
900 : /**
901 : * @brief Set cleaning parameter in given cache
902 : *
903 : * @attention This changes only runtime state. To make changes persistent
904 : * use function ocf_mngt_cache_save().
905 : *
906 : * @param[in] cache Cache handle
907 : * @param[in] type Cleaning policy type
908 : * @param[in] param_id Cleaning policy parameter id
909 : * @param[in] param_value Cleaning policy parameter value
910 : *
911 : * @retval 0 Parameter has been set successfully
912 : * @retval Non-zero Error occurred and parameter has not been set
913 : */
914 : int ocf_mngt_cache_cleaning_set_param(ocf_cache_t cache, ocf_cleaning_t type,
915 : uint32_t param_id, uint32_t param_value);
916 :
917 : /**
918 : * @brief Get cleaning parameter from given cache
919 : *
920 : * @param[in] cache Cache handle
921 : * @param[in] type Cleaning policy type
922 : * @param[in] param_id Cleaning policy parameter id
923 : * @param[out] param_value Variable to store parameter value
924 : *
925 : * @retval 0 Parameter has been get successfully
926 : * @retval Non-zero Error occurred and parameter has not been get
927 : */
928 : int ocf_mngt_cache_cleaning_get_param(ocf_cache_t cache,ocf_cleaning_t type,
929 : uint32_t param_id, uint32_t *param_value);
930 :
931 : /**
932 : * @brief Set promotion policy in given cache
933 : *
934 : * @attention This changes only runtime state. To make changes persistent
935 : * use function ocf_mngt_cache_save().
936 : *
937 : * @param[in] cache Cache handle
938 : * @param[in] type Promotion policy type
939 : *
940 : * @retval 0 Policy has been set successfully
941 : * @retval Non-zero Error occurred and policy has not been set
942 : */
943 : int ocf_mngt_cache_promotion_set_policy(ocf_cache_t cache, ocf_promotion_t type);
944 :
945 : /**
946 : * @brief Get promotion policy in given cache
947 : *
948 : * @param[in] cache Cache handle
949 : * @param[out] type Policy type
950 : *
951 : * @retval 0 success
952 : * @retval Non-zero Error occurred and policy type could not be retrieved
953 : */
954 : int ocf_mngt_cache_promotion_get_policy(ocf_cache_t cache, ocf_promotion_t *type);
955 :
956 : /**
957 : * @brief Set promotion policy parameter for given cache
958 : *
959 : * @param[in] cache Cache handle
960 : * @param[in] type Promotion policy type
961 : * @param[in] param_id Promotion policy parameter id
962 : * @param[in] param_value Promotion policy parameter value
963 : *
964 : * @retval 0 Parameter has been set successfully
965 : * @retval Non-zero Error occurred and parameter has not been set
966 : */
967 : int ocf_mngt_cache_promotion_set_param(ocf_cache_t cache, ocf_promotion_t type,
968 : uint8_t param_id, uint32_t param_value);
969 :
970 : /**
971 : * @brief Get promotion policy parameter for given cache
972 : *
973 : * @param[in] cache Cache handle
974 : * @param[in] type Promotion policy type
975 : * @param[in] param_id Promotion policy parameter id
976 : * @param[out] param_value Variable to store parameter value
977 : *
978 : * @retval 0 Parameter has been retrieved successfully
979 : * @retval Non-zero Error occurred and parameter has not been retrieved
980 : */
981 : int ocf_mngt_cache_promotion_get_param(ocf_cache_t cache, ocf_promotion_t type,
982 : uint8_t param_id, uint32_t *param_value);
983 :
984 : /**
985 : * @brief IO class configuration
986 : */
987 : struct ocf_mngt_io_class_config {
988 : /**
989 : * @brief IO class ID
990 : */
991 : uint32_t class_id;
992 :
993 : /**
994 : * @brief IO class maximum size
995 : */
996 : uint32_t max_size;
997 :
998 : /**
999 : * @brief IO class name
1000 : */
1001 : const char *name;
1002 :
1003 : /**
1004 : * @brief IO class cache mode
1005 : */
1006 : ocf_cache_mode_t cache_mode;
1007 :
1008 : /**
1009 : * @brief IO class eviction priority
1010 : */
1011 : int16_t prio;
1012 : };
1013 :
1014 : struct ocf_mngt_io_classes_config {
1015 : struct ocf_mngt_io_class_config config[OCF_USER_IO_CLASS_MAX];
1016 : };
1017 :
1018 : /**
1019 : * @brief Configure IO classes in given cache
1020 : *
1021 : * @attention This changes only runtime state. To make changes persistent
1022 : * use function ocf_mngt_cache_save().
1023 : *
1024 : * @param[in] cache Cache handle
1025 : * @param[in] cfg IO class configuration
1026 : *
1027 : * @retval 0 Configuration have been set successfully
1028 : * @retval Non-zero Error occurred and configuration not been set
1029 : */
1030 : int ocf_mngt_cache_io_classes_configure(ocf_cache_t cache,
1031 : const struct ocf_mngt_io_classes_config *cfg);
1032 :
1033 : /**
1034 : * @brief Asociate new UUID value with given core
1035 : *
1036 : * @attention This changes only runtime state. To make changes persistent
1037 : * use function ocf_mngt_cache_save().
1038 : *
1039 : * @param[in] core Core object
1040 : * @param[in] uuid new core uuid
1041 : *
1042 : * @retval 0 Success
1043 : * @retval Non-zero Fail
1044 : */
1045 : int ocf_mngt_core_set_uuid(ocf_core_t core, const struct ocf_volume_uuid *uuid);
1046 :
1047 : /**
1048 : * @brief Set persistent user metadata for given core
1049 : *
1050 : * @attention This changes only runtime state. To make changes persistent
1051 : * use function ocf_mngt_cache_save().
1052 : *
1053 : * @param[in] core Core object
1054 : * @param[in] data User data buffer
1055 : * @param[in] size Size of user data buffer
1056 : *
1057 : * @retval 0 Success
1058 : * @retval Non-zero Core getting failed
1059 : */
1060 : int ocf_mngt_core_set_user_metadata(ocf_core_t core, void *data, size_t size);
1061 :
1062 : /**
1063 : * @brief Get persistent user metadata from given core
1064 : *
1065 : * @param[in] core Core object
1066 : * @param[out] data User data buffer
1067 : * @param[in] size Size of user data buffer
1068 : *
1069 : * @retval 0 Success
1070 : * @retval Non-zero Core getting failed
1071 : */
1072 : int ocf_mngt_core_get_user_metadata(ocf_core_t core, void *data, size_t size);
1073 :
1074 : /**
1075 : * @brief Set core sequential cutoff threshold
1076 : *
1077 : * @attention This changes only runtime state. To make changes persistent
1078 : * use function ocf_mngt_cache_save().
1079 : *
1080 : * @param[in] core Core handle
1081 : * @param[in] thresh threshold in bytes for sequential cutoff
1082 : *
1083 : * @retval 0 Sequential cutoff threshold has been set successfully
1084 : * @retval Non-zero Error occured and threshold hasn't been updated
1085 : */
1086 : int ocf_mngt_core_set_seq_cutoff_threshold(ocf_core_t core, uint32_t thresh);
1087 :
1088 : /**
1089 : * @brief Set sequential cutoff threshold for all cores in cache
1090 : *
1091 : * @attention This changes only runtime state. To make changes persistent
1092 : * use function ocf_mngt_cache_save().
1093 : *
1094 : * @param[in] cache Cache handle
1095 : * @param[in] thresh threshold in bytes for sequential cutoff
1096 : *
1097 : * @retval 0 Sequential cutoff threshold has been set successfully
1098 : * @retval Non-zero Error occured and threshold hasn't been updated
1099 : */
1100 : int ocf_mngt_core_set_seq_cutoff_threshold_all(ocf_cache_t cache,
1101 : uint32_t thresh);
1102 :
1103 : /**
1104 : * @brief Get core sequential cutoff threshold
1105 : *
1106 : * @param[in] core Core handle
1107 : * @param[in] thresh threshold in bytes for sequential cutoff
1108 : *
1109 : * @retval 0 Sequential cutoff threshold has been get successfully
1110 : * @retval Non-zero Error occured
1111 : */
1112 : int ocf_mngt_core_get_seq_cutoff_threshold(ocf_core_t core, uint32_t *thresh);
1113 :
1114 : /**
1115 : * @brief Set core sequential cutoff policy
1116 : *
1117 : * @attention This changes only runtime state. To make changes persistent
1118 : * use function ocf_mngt_cache_save().
1119 : *
1120 : * @param[in] core Core handle
1121 : * @param[in] policy sequential cutoff policy
1122 : *
1123 : * @retval 0 Sequential cutoff policy has been set successfully
1124 : * @retval Non-zero Error occured and policy hasn't been updated
1125 : */
1126 : int ocf_mngt_core_set_seq_cutoff_policy(ocf_core_t core,
1127 : ocf_seq_cutoff_policy policy);
1128 :
1129 : /**
1130 : * @brief Set sequential cutoff policy for all cores in cache
1131 : *
1132 : * @attention This changes only runtime state. To make changes persistent
1133 : * use function ocf_mngt_cache_save().
1134 : *
1135 : * @param[in] cache Cache handle
1136 : * @param[in] policy sequential cutoff policy
1137 : *
1138 : * @retval 0 Sequential cutoff policy has been set successfully
1139 : * @retval Non-zero Error occured and policy hasn't been updated
1140 : */
1141 : int ocf_mngt_core_set_seq_cutoff_policy_all(ocf_cache_t cache,
1142 : ocf_seq_cutoff_policy policy);
1143 :
1144 : /**
1145 : * @brief Get core sequential cutoff policy
1146 : *
1147 : * @param[in] core Core handle
1148 : * @param[in] policy sequential cutoff policy
1149 : *
1150 : * @retval 0 Sequential cutoff policy has been get successfully
1151 : * @retval Non-zero Error occured
1152 : */
1153 : int ocf_mngt_core_get_seq_cutoff_policy(ocf_core_t core,
1154 : ocf_seq_cutoff_policy *policy);
1155 :
1156 : /**
1157 : * @brief Set core sequential cutoff promotion request count
1158 : *
1159 : * @attention This changes only runtime state. To make changes persistent
1160 : * use function ocf_mngt_cache_save().
1161 : *
1162 : * @param[in] core Core handle
1163 : * @param[in] count promotion request count
1164 : *
1165 : * @retval 0 Sequential cutoff promotion requets count has been set successfully
1166 : * @retval Non-zero Error occured and request count hasn't been updated
1167 : */
1168 : int ocf_mngt_core_set_seq_cutoff_promotion_count(ocf_core_t core,
1169 : uint32_t count);
1170 :
1171 : /**
1172 : * @brief Set sequential cutoff promotion request count for all cores in cache
1173 : *
1174 : * @attention This changes only runtime state. To make changes persistent
1175 : * use function ocf_mngt_cache_save().
1176 : *
1177 : * @param[in] cache Cache handle
1178 : * @param[in] count promotion request count
1179 : *
1180 : * @retval 0 Sequential cutoff promotion request count has been set successfully
1181 : * @retval Non-zero Error occured and request count hasn't been updated
1182 : */
1183 : int ocf_mngt_core_set_seq_cutoff_promotion_count_all(ocf_cache_t cache,
1184 : uint32_t count);
1185 :
1186 : /**
1187 : * @brief Get core sequential cutoff promotion threshold
1188 : *
1189 : * @param[in] core Core handle
1190 : * @param[out] count promotion request count
1191 : *
1192 : * @retval 0 Sequential cutoff promotion request count has been get successfully
1193 : * @retval Non-zero Error occured
1194 : */
1195 : int ocf_mngt_core_get_seq_cutoff_promotion_count(ocf_core_t core,
1196 : uint32_t *count);
1197 :
1198 : /**
1199 : * @brief Set whether to promote core sequential cutoff stream
1200 : * to global structures when threshold is reached
1201 : *
1202 : * @attention This changes only runtime state. To make changes persistent
1203 : * use function ocf_mngt_cache_save().
1204 : *
1205 : * @param[in] core Core handle
1206 : * @param[in] promote Whether to promote or not
1207 : *
1208 : * @retval 0 Sequential cutoff promote on threshold has been set successfully
1209 : * @retval Non-zero Error occured and promote on threshold hasn't been updated
1210 : */
1211 : int ocf_mngt_core_set_seq_cutoff_promote_on_threshold(ocf_core_t core,
1212 : bool promote);
1213 :
1214 : /**
1215 : * @brief Set whether to promote sequential cutoff stream
1216 : * to global structures when threshold is reached for all cores in cache
1217 : *
1218 : * @attention This changes only runtime state. To make changes persistent
1219 : * use function ocf_mngt_cache_save().
1220 : *
1221 : * @param[in] cache Cache handle
1222 : * @param[in] promote Whether to promote or not
1223 : *
1224 : * @retval 0 Sequential cutoff promote on threshold has been set successfully
1225 : * @retval Non-zero Error occured and promote on threshold hasn't been updated
1226 : */
1227 : int ocf_mngt_core_set_seq_cutoff_promote_on_threshold_all(ocf_cache_t cache,
1228 : bool promote);
1229 :
1230 : /**
1231 : * @brief Get core sequential cutoff promote on threshold switch value
1232 : *
1233 : * @param[in] core Core handle
1234 : * @param[out] promote Promote on threshold
1235 : *
1236 : * @retval 0 Sequential cutoff promote on threshold retrieved successfully
1237 : * @retval Non-zero Error occured and value could not be retrieved
1238 : */
1239 : int ocf_mngt_core_get_seq_cutoff_promote_on_threshold(ocf_core_t core,
1240 : bool *promote);
1241 :
1242 : /**
1243 : * @brief Set cache fallback Pass Through error threshold
1244 : *
1245 : * @param[in] cache Cache handle
1246 : * @param[in] threshold Value to be set as threshold
1247 : *
1248 : * @retval 0 Fallback-PT threshold have been set successfully
1249 : * @retval Non-zero Error occurred
1250 : */
1251 : int ocf_mngt_cache_set_fallback_pt_error_threshold(ocf_cache_t cache,
1252 : uint32_t threshold);
1253 :
1254 : /**
1255 : * @brief Get cache fallback Pass Through error threshold
1256 : *
1257 : * @param[in] cache Cache handle
1258 : * @param[out] threshold Fallback-PT threshold
1259 : *
1260 : * @retval 0 Fallback-PT threshold have been get successfully
1261 : * @retval Non-zero Error occurred
1262 : */
1263 : int ocf_mngt_cache_get_fallback_pt_error_threshold(ocf_cache_t cache,
1264 : uint32_t *threshold);
1265 :
1266 : /**
1267 : * @brief Reset cache fallback Pass Through error counter
1268 : *
1269 : * @param[in] cache Cache handle
1270 : *
1271 : * @retval 0 Threshold have been reset successfully
1272 : * @retval Non-zero Error occured
1273 : */
1274 : int ocf_mngt_cache_reset_fallback_pt_error_counter(ocf_cache_t cache);
1275 :
1276 : /**
1277 : * @brief Get core pool count
1278 : *
1279 : * @param[in] ctx OCF context
1280 : *
1281 : * @retval Number of cores in core pool
1282 : */
1283 : int ocf_mngt_core_pool_get_count(ocf_ctx_t ctx);
1284 :
1285 : /**
1286 : * @brief Add core to pool
1287 : *
1288 : * @param[in] ctx OCF context
1289 : * @param[in] uuid Cache volume UUID
1290 : * @param[in] type OCF core volume type
1291 : *
1292 : * @retval 0 Core added to pool successfully
1293 : * @retval Non-zero Error occurred and adding core to poll failed
1294 : */
1295 : int ocf_mngt_core_pool_add(ocf_ctx_t ctx, ocf_uuid_t uuid, uint8_t type);
1296 :
1297 : /**
1298 : * @brief Add core to pool
1299 : *
1300 : * @param[in] ctx OCF context
1301 : * @param[in] uuid Cache volume UUID
1302 : * @param[in] type OCF core volume type
1303 : *
1304 : * @retval Handler to object with same UUID
1305 : * @retval NULL Not found object with that id
1306 : */
1307 : ocf_volume_t ocf_mngt_core_pool_lookup(ocf_ctx_t ctx, ocf_uuid_t uuid,
1308 : ocf_volume_type_t type);
1309 : /**
1310 : * @brief Iterate over all object in pool and call visitor callback
1311 : *
1312 : * @param[in] ctx OCF context
1313 : * @param[in] visitor Visitor callback
1314 : * @param[in] visior_ctx CContext for visitor callback
1315 : *
1316 : * @retval Handler to object with same UUID
1317 : * @retval NULL Not found object with that id
1318 : */
1319 : int ocf_mngt_core_pool_visit(ocf_ctx_t ctx,
1320 : int (*visitor)(ocf_uuid_t, void *), void *visitor_ctx);
1321 :
1322 : /**
1323 : * @brief Remove volume from pool
1324 : *
1325 : * Important: This function destroys volume instance but doesn't close it,
1326 : * so it should be either moved or closed before calling this function.
1327 : *
1328 : * @param[in] ctx OCF context
1329 : * @param[in] volume Core volume
1330 : */
1331 : void ocf_mngt_core_pool_remove(ocf_ctx_t ctx, ocf_volume_t volume);
1332 :
1333 : #endif /* __OCF_CACHE_H__ */
|