1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (c) Intel Corporation. 3 * All rights reserved. 4 */ 5 6 #ifndef FTL_MNGT_H 7 #define FTL_MNGT_H 8 9 #include "spdk/stdinc.h" 10 #include "spdk/ftl.h" 11 12 struct spdk_ftl_dev; 13 struct ftl_mngt_process; 14 15 /** 16 * The FTL management callback function 17 * 18 * @param dev FTL device 19 * @param mngt FTL management handle 20 */ 21 typedef void (*ftl_mngt_fn)(struct spdk_ftl_dev *dev, struct ftl_mngt_process *mngt); 22 23 /** 24 * The FTL management step descriptior 25 */ 26 struct ftl_mngt_step_desc { 27 /** 28 * Name of the step 29 */ 30 const char *name; 31 32 /** 33 * Size of the step argument (context) 34 * 35 * The step context will be allocated before execution of step's 36 * callback. 37 * 38 * @note The context can be reallocated (freed and newly allocated 39 * when calling ftl_mngt_alloc_step_ctx). The main usage is the ability 40 * to set this value to 0 and only allocate as needed if the step is 41 * going to be extremely similar - eg. recovery from shared memory and 42 * disk - in case of shm all the data is already available in memory, while 43 * recovery from disk needs extra context to be able to synchronize IO. This 44 * allows for saving a little bit of time on alloc/dealloc in the cases where 45 * execution time may be critical. 46 * @note It doesn't work like realloc 47 * @note The context can be retrieved within callback when calling 48 * ftl_mngt_get_step_ctx 49 */ 50 size_t ctx_size; 51 52 /** 53 * Step callback function 54 */ 55 ftl_mngt_fn action; 56 57 /** 58 * It the step requires cleanup this is right place to put your handler. 59 * When a FTL management process fails cleanup callbacks are executed 60 * in rollback procedure. Cleanup functions are executed in reverse 61 * order to actions already called. 62 */ 63 ftl_mngt_fn cleanup; 64 }; 65 66 /** 67 * The FTL management process descriptor 68 */ 69 struct ftl_mngt_process_desc { 70 /** 71 * The name of the process 72 */ 73 const char *name; 74 75 /** 76 * Size of the process argument (context) 77 * 78 * The process context will be allocated before execution of the first 79 * step 80 * 81 * @note To get context of the process within FTL management callback, 82 * execute ftl_mngt_get_process_ctx 83 */ 84 size_t ctx_size; 85 86 /** 87 * Pointer to the additional error handler when the process fails 88 */ 89 ftl_mngt_fn error_handler; 90 91 /** 92 * The FTL process steps 93 * 94 * The process context will be allocated before execution of the first 95 * step 96 * 97 * @note The step array terminator shall end with action equals NULL 98 */ 99 struct ftl_mngt_step_desc steps[]; 100 }; 101 102 /** 103 * @brief Executes the FTL management process defined by the process descriptor 104 * 105 * In case of an error all already executed steps will have their rollback functions 106 * called in reverse order. 107 * 108 * @param dev FTL device 109 * @param process The descriptor of process to be executed 110 * @param cb Caller callback 111 * @param cb_ctx Caller context 112 * 113 * @return Result of invoking the operation 114 * @retval 0 - The FTL management process has been started 115 * @retval Non-zero An error occurred when starting The FTL management process 116 */ 117 int ftl_mngt_process_execute(struct spdk_ftl_dev *dev, 118 const struct ftl_mngt_process_desc *process, 119 ftl_mngt_fn cb, void *cb_ctx); 120 121 /** 122 * @brief Executes rollback on the FTL management process defined by the process 123 * descriptor 124 * 125 * All cleanup function from steps will be executed in reversed order 126 * 127 * @param dev FTL device 128 * @param process The descriptor of process to be rollback 129 * @param cb Caller callback 130 * @param cb_ctx Caller context 131 * 132 * @return Result of invoking the rollback operation 133 * @retval 0 - Rollback of the FTL management process has been started 134 * @retval Non-zero An error occurred when starting the rollback 135 */ 136 int ftl_mngt_process_rollback(struct spdk_ftl_dev *dev, 137 const struct ftl_mngt_process_desc *process, 138 ftl_mngt_fn cb, void *cb_ctx); 139 140 /* 141 * FTL management API for steps 142 */ 143 144 /** 145 * @brief Gets FTL device 146 * 147 * @param mngt FTL management handle 148 * 149 * @note This function can be invoked within step handler only 150 * 151 * @return FTL device 152 */ 153 struct spdk_ftl_dev *ftl_mngt_get_dev(struct ftl_mngt_process *mngt); 154 155 /** 156 * @brief Allocates a context for the management step 157 * 158 * @param mngt FTL management handle 159 * @param size Size of the step context 160 * 161 * @note This function can be invoked within ftl_mngt_fn callback only 162 * 163 * @return Operation result 164 * @retval 0 Operation successful 165 * @retval Non-zero Operation failure 166 */ 167 int ftl_mngt_alloc_step_ctx(struct ftl_mngt_process *mngt, size_t size); 168 169 /** 170 * @brief Gets the management step context 171 * 172 * @param mngt FTL management handle 173 * 174 * @note This function can be invoked within ftl_mngt_fn callback only 175 * 176 * @return Context of the step containing pointer to buffer and its size 177 */ 178 void *ftl_mngt_get_step_ctx(struct ftl_mngt_process *mngt); 179 180 /** 181 * @brief Gets the management process context 182 * 183 * @param mngt FTL management handle 184 * 185 * @note This function can be invoked within ftl_mngt_fn callback only 186 * 187 * @return Context of the process containing pointer to buffer and its size 188 */ 189 void *ftl_mngt_get_process_ctx(struct ftl_mngt_process *mngt); 190 191 /** 192 * @brief Gets the caller context 193 * 194 * @param mngt FTL management handle 195 * 196 * @note This function can be invoked within ftl_mngt_fn callback only 197 * 198 * @return Pointer to the caller context 199 */ 200 void *ftl_mngt_get_caller_ctx(struct ftl_mngt_process *mngt); 201 202 /** 203 * @brief Gets the status of executed management process 204 * 205 * @param mngt FTL management handle 206 * 207 * @note This function can be invoked within ftl_mngt_fn callback only 208 * 209 * @return The operation result of the management process 210 * @retval 0 Operation successful 211 * @retval Non-zero Operation failure 212 */ 213 int ftl_mngt_get_status(struct ftl_mngt_process *mngt); 214 215 /** 216 * @brief Finishes the management process immediately 217 * 218 * @note This function can be invoked within ftl_mngt_fn callback only 219 * 220 * @param mngt FTL management handle of process to be finished 221 */ 222 void ftl_mngt_finish(struct ftl_mngt_process *mngt); 223 224 /** 225 * @brief Completes the step currently in progress and jump to a next one 226 * 227 * If no more steps to be executed then the management process is finished and 228 * caller callback is invoked 229 * 230 * @note This function can be invoked within ftl_mngt_fn callback only 231 * 232 * @param mngt FTL management handle 233 */ 234 void ftl_mngt_next_step(struct ftl_mngt_process *mngt); 235 236 /** 237 * @brief Skips the step currently in progress and jump to a next one 238 * 239 * @note This function can be invoked within ftl_mngt_fn callback only 240 * 241 * @param mngt FTL management handle 242 */ 243 void ftl_mngt_skip_step(struct ftl_mngt_process *mngt); 244 245 /** 246 * @brief Continue the step currently in progress 247 * 248 * This causes invoking the same step handler in next iteration of the 249 * management process. This mechanism can be used by a job when polling for 250 * something. 251 * 252 * @note This function can be invoked within ftl_mngt_fn callback only 253 * 254 * @param mngt FTL management handle 255 */ 256 void ftl_mngt_continue_step(struct ftl_mngt_process *mngt); 257 258 /** 259 * @brief Fail the step currently in progress. 260 * 261 * It stops executing all steps and starts the rollback procedure (calling 262 * the cleanup functions of all already executed steps). 263 * If executed from a cleanup function, it will stop executing and the following 264 * cleanup functions (if any) will be executed. 265 * 266 * @param mngt FTL management handle 267 */ 268 void ftl_mngt_fail_step(struct ftl_mngt_process *mngt); 269 270 /** 271 * @brief Calls another management process 272 * 273 * Ends the current step and executes specified process and finally continues 274 * executing the the remaining steps 275 * 276 * @param mngt The management handle 277 * @param process The management process to be called 278 */ 279 void ftl_mngt_call_process(struct ftl_mngt_process *mngt, 280 const struct ftl_mngt_process_desc *process); 281 282 /** 283 * @brief Calls rollback steps of another management process 284 * 285 * Ends the current step and executes rollback steps of specified process 286 * and finally continues executing the remaining steps in the original process 287 * 288 * @param mngt The management handle 289 * @param process The management process to be called to execute rollback 290 */ 291 void ftl_mngt_call_process_rollback(struct ftl_mngt_process *mngt, 292 const struct ftl_mngt_process_desc *process); 293 294 #endif /* LIB_FTL_FTL_MNGT_H */ 295