1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2018 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 #ifndef SPDK_FTL_H 7 #define SPDK_FTL_H 8 9 #include "spdk/stdinc.h" 10 #include "spdk/uuid.h" 11 #include "spdk/thread.h" 12 #include "spdk/bdev.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 struct spdk_ftl_dev; 19 struct ftl_io; 20 21 /* Limit thresholds */ 22 enum { 23 SPDK_FTL_LIMIT_CRIT, 24 SPDK_FTL_LIMIT_HIGH, 25 SPDK_FTL_LIMIT_LOW, 26 SPDK_FTL_LIMIT_START, 27 SPDK_FTL_LIMIT_MAX 28 }; 29 30 struct ftl_stats_error { 31 uint64_t media; 32 uint64_t crc; 33 uint64_t other; 34 }; 35 36 struct ftl_stats_group { 37 uint64_t ios; 38 uint64_t blocks; 39 struct ftl_stats_error errors; 40 }; 41 42 struct ftl_stats_entry { 43 struct ftl_stats_group read; 44 struct ftl_stats_group write; 45 }; 46 47 enum ftl_stats_type { 48 FTL_STATS_TYPE_USER = 0, 49 FTL_STATS_TYPE_CMP, 50 FTL_STATS_TYPE_GC, 51 FTL_STATS_TYPE_MD_BASE, 52 FTL_STATS_TYPE_MD_NV_CACHE, 53 FTL_STATS_TYPE_L2P, 54 FTL_STATS_TYPE_MAX, 55 }; 56 57 struct ftl_stats { 58 /* Number of times write limits were triggered by FTL writers 59 * (gc and compaction) dependent on number of free bands. GC starts at 60 * SPDK_FTL_LIMIT_START level, while at SPDK_FTL_LIMIT_CRIT compaction stops 61 * and only GC is allowed to work. 62 */ 63 uint64_t limits[SPDK_FTL_LIMIT_MAX]; 64 65 /* Total number of blocks with IO to the underlying devices 66 * 1. nv cache read/write 67 * 2. base bdev read/write 68 */ 69 uint64_t io_activity_total; 70 71 struct ftl_stats_entry entries[FTL_STATS_TYPE_MAX]; 72 }; 73 74 typedef void (*spdk_ftl_stats_fn)(struct ftl_stats *stats, void *cb_arg); 75 76 /* 77 * FTL configuration. 78 * 79 * NOTE: Do not change the layout of this structure. Only add new fields at the end. 80 */ 81 struct spdk_ftl_conf { 82 /* Device's name */ 83 char *name; 84 85 /* Device UUID (valid when restoring device from disk) */ 86 struct spdk_uuid uuid; 87 88 /* Percentage of base device blocks not exposed to the user */ 89 uint64_t overprovisioning; 90 91 /* l2p cache size that could reside in DRAM (in MiB) */ 92 size_t l2p_dram_limit; 93 94 /* Core mask - core thread plus additional relocation threads */ 95 char *core_mask; 96 97 /* IO pool size per user thread */ 98 size_t user_io_pool_size; 99 100 /* User writes limits */ 101 size_t limits[SPDK_FTL_LIMIT_MAX]; 102 103 /* FTL startup mode mask, see spdk_ftl_mode enum for possible values */ 104 uint32_t mode; 105 106 struct { 107 /* Start compaction when full chunks exceed given % of entire chunks */ 108 uint32_t chunk_compaction_threshold; 109 110 /* Percentage of chunks to maintain free */ 111 uint32_t chunk_free_target; 112 } nv_cache; 113 114 /* Hole at bytes 0x60 - 0x67. */ 115 uint8_t reserved[4]; 116 117 /* Name of base block device (zoned or non-zoned) */ 118 char *base_bdev; 119 120 /* Name of cache block device (must support extended metadata) */ 121 char *cache_bdev; 122 123 /* Enable fast shutdown path */ 124 bool fast_shutdown; 125 126 /* Hole at bytes 0x79 - 0x7f. */ 127 uint8_t reserved2[7]; 128 129 /* 130 * The size of spdk_ftl_conf according to the caller of this library is used for ABI 131 * compatibility. The library uses this field to know how many fields in this 132 * structure are valid. And the library will populate any remaining fields with default values. 133 */ 134 size_t conf_size; 135 } __attribute__((packed)); 136 SPDK_STATIC_ASSERT(sizeof(struct spdk_ftl_conf) == 136, "Incorrect size"); 137 138 enum spdk_ftl_mode { 139 /* Create new device */ 140 SPDK_FTL_MODE_CREATE = (1 << 0), 141 }; 142 143 /* 144 * FTL device attributes. 145 * 146 * NOTE: Do not change the layout of this structure. Only add new fields at the end. 147 */ 148 struct spdk_ftl_attrs { 149 /* Number of logical blocks */ 150 uint64_t num_blocks; 151 /* Logical block size */ 152 uint64_t block_size; 153 /* Optimal IO size - bdev layer will split requests over this size */ 154 uint64_t optimum_io_size; 155 }; 156 157 typedef void (*spdk_ftl_fn)(void *cb_arg, int status); 158 typedef void (*spdk_ftl_init_fn)(struct spdk_ftl_dev *dev, void *cb_arg, int status); 159 160 /** 161 * Initializes the FTL library. 162 * 163 * @return 0 on success, negative errno otherwise. 164 */ 165 int spdk_ftl_init(void); 166 167 /** 168 * Deinitializes the FTL library. 169 */ 170 void spdk_ftl_fini(void); 171 172 /** 173 * Initialize the FTL on the given pair of bdevs - base and cache bdev. 174 * Upon receiving a successful completion callback user is free to use I/O calls. 175 * 176 * \param conf configuration for new device 177 * \param cb callback function to call when the device is created 178 * \param cb_arg callback's argument 179 * 180 * \return 0 if initialization was started successfully, negative errno otherwise. 181 */ 182 int spdk_ftl_dev_init(const struct spdk_ftl_conf *conf, spdk_ftl_init_fn cb, void *cb_arg); 183 184 /** 185 * Deinitialize and free given device. 186 * 187 * \param dev device 188 * \param cb callback function to call when the device is freed 189 * \param cb_arg callback's argument 190 * 191 * \return 0 if deinitialization was started successfully, negative errno otherwise. 192 */ 193 int spdk_ftl_dev_free(struct spdk_ftl_dev *dev, spdk_ftl_fn cb, void *cb_arg); 194 195 /** 196 * Retrieve device’s attributes. 197 * 198 * \param dev device 199 * \param attr Attribute structure to fill 200 * \param attrs_size Must be set to sizeof(struct spdk_ftl_attrs) 201 */ 202 void spdk_ftl_dev_get_attrs(const struct spdk_ftl_dev *dev, struct spdk_ftl_attrs *attr, 203 size_t attrs_size); 204 205 /** 206 * Retrieve device’s configuration. 207 * 208 * \param dev device 209 * \param conf FTL configuration structure to fill 210 * \param conf_size Must be set to sizeof(struct spdk_ftl_conf) 211 */ 212 void spdk_ftl_dev_get_conf(const struct spdk_ftl_dev *dev, struct spdk_ftl_conf *conf, 213 size_t conf_size); 214 215 /** 216 * Obtain an I/O channel for the device. 217 * 218 * \param dev device 219 * 220 * \return A handle to the I/O channel or NULL on failure. 221 */ 222 struct spdk_io_channel *spdk_ftl_get_io_channel(struct spdk_ftl_dev *dev); 223 224 /** 225 * Make a deep copy of an FTL configuration structure 226 * 227 * \param dst The destination FTL configuration 228 * \param src The source FTL configuration 229 */ 230 int spdk_ftl_conf_copy(struct spdk_ftl_conf *dst, const struct spdk_ftl_conf *src); 231 232 /** 233 * Release the FTL configuration resources. This does not free the structure itself. 234 * 235 * \param conf FTL configuration to deinitialize 236 */ 237 void spdk_ftl_conf_deinit(struct spdk_ftl_conf *conf); 238 239 /** 240 * Initialize FTL configuration structure with default values. 241 * 242 * \param conf FTL configuration to initialize 243 * \param conf_size Must be set to sizeof(struct spdk_ftl_conf) 244 */ 245 void spdk_ftl_get_default_conf(struct spdk_ftl_conf *conf, size_t conf_size); 246 247 /** 248 * Submits a read to the specified device. 249 * 250 * \param dev Device 251 * \param io Allocated ftl_io 252 * \param ch I/O channel 253 * \param lba Starting LBA to read the data 254 * \param lba_cnt Number of sectors to read 255 * \param iov Single IO vector or pointer to IO vector table 256 * \param iov_cnt Number of IO vectors 257 * \param cb_fn Callback function to invoke when the I/O is completed 258 * \param cb_arg Argument to pass to the callback function 259 * 260 * \return 0 if successfully submitted, negative errno otherwise. 261 */ 262 int spdk_ftl_readv(struct spdk_ftl_dev *dev, struct ftl_io *io, struct spdk_io_channel *ch, 263 uint64_t lba, uint64_t lba_cnt, 264 struct iovec *iov, size_t iov_cnt, spdk_ftl_fn cb_fn, void *cb_arg); 265 266 /** 267 * Submits a write to the specified device. 268 * 269 * \param dev Device 270 * \param io Allocated ftl_io 271 * \param ch I/O channel 272 * \param lba Starting LBA to write the data 273 * \param lba_cnt Number of sectors to write 274 * \param iov Single IO vector or pointer to IO vector table 275 * \param iov_cnt Number of IO vectors 276 * \param cb_fn Callback function to invoke when the I/O is completed 277 * \param cb_arg Argument to pass to the callback function 278 * 279 * \return 0 if successfully submitted, negative errno otherwise. 280 */ 281 int spdk_ftl_writev(struct spdk_ftl_dev *dev, struct ftl_io *io, struct spdk_io_channel *ch, 282 uint64_t lba, uint64_t lba_cnt, 283 struct iovec *iov, size_t iov_cnt, spdk_ftl_fn cb_fn, void *cb_arg); 284 285 /** 286 * Submits a unmap to the specified device. 287 * 288 * \param dev Device 289 * \param io Allocated ftl_io 290 * \param ch I/O channel 291 * \param lba Starting LBA to write the data 292 * \param lba_cnt Number of blocks to unmap 293 * \param cb_fn Callback function to invoke when the I/O is completed 294 * \param cb_arg Argument to pass to the callback function 295 * 296 * \return 0 if successfully submitted, negative errno otherwise. 297 */ 298 int spdk_ftl_unmap(struct spdk_ftl_dev *dev, struct ftl_io *io, struct spdk_io_channel *ch, 299 uint64_t lba, uint64_t lba_cnt, spdk_ftl_fn cb_fn, void *cb_arg); 300 301 /** 302 * Returns the size of ftl_io struct that needs to be passed to spdk_ftl_read/write 303 * 304 * \return The size of struct 305 */ 306 size_t spdk_ftl_io_size(void); 307 308 /** 309 * Enable fast shutdown. 310 * 311 * During fast shutdown FTL will keep the necessary metadata in shared memory instead 312 * of serializing it to storage. This allows for shorter downtime during upgrade process. 313 */ 314 void spdk_ftl_dev_set_fast_shutdown(struct spdk_ftl_dev *dev, bool fast_shutdown); 315 316 /* 317 * Returns current FTL I/O statistics. 318 * 319 * \param dev Device 320 * \param stats Allocated ftl_stats 321 * \param cb_fn Callback function to invoke when the call is completed 322 * \param cb_arg Argument to pass to the callback function 323 * 324 * \return 0 if successfully submitted, negative errno otherwise. 325 */ 326 int spdk_ftl_get_stats(struct spdk_ftl_dev *dev, struct ftl_stats *stats, spdk_ftl_stats_fn cb_fn, 327 void *cb_arg); 328 329 #ifdef __cplusplus 330 } 331 #endif 332 333 #endif /* SPDK_FTL_H */ 334