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