1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (c) 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 spdk_ftl_conf { 31 /* Device's name */ 32 char *name; 33 34 /* Device UUID (valid when restoring device from disk) */ 35 struct spdk_uuid uuid; 36 37 /* Percentage of base device blocks not exposed to the user */ 38 uint64_t overprovisioning; 39 40 /* l2p cache size that could reside in DRAM (in MiB) */ 41 size_t l2p_dram_limit; 42 43 /* Core mask - core thread plus additional relocation threads */ 44 char *core_mask; 45 46 /* IO pool size per user thread */ 47 size_t user_io_pool_size; 48 49 /* User writes limits */ 50 size_t limits[SPDK_FTL_LIMIT_MAX]; 51 52 /* FTL startup mode mask, see spdk_ftl_mode enum for possible values */ 53 uint32_t mode; 54 55 struct { 56 /* Start compaction when full chunks exceed given % of entire chunks */ 57 uint32_t chunk_compaction_threshold; 58 } nv_cache; 59 60 /* Name of base block device (zoned or non-zoned) */ 61 char *base_bdev; 62 63 /* Name of cache block device (must support extended metadata) */ 64 char *cache_bdev; 65 /* Enable fast shutdown path */ 66 bool fast_shutdown; 67 }; 68 69 enum spdk_ftl_mode { 70 /* Create new device */ 71 SPDK_FTL_MODE_CREATE = (1 << 0), 72 }; 73 74 struct spdk_ftl_attrs { 75 /* Number of logical blocks */ 76 uint64_t num_blocks; 77 /* Logical block size */ 78 uint64_t block_size; 79 /* Optimal IO size - bdev layer will split requests over this size */ 80 uint64_t optimum_io_size; 81 }; 82 83 typedef void (*spdk_ftl_fn)(void *cb_arg, int status); 84 typedef void (*spdk_ftl_init_fn)(struct spdk_ftl_dev *dev, void *cb_arg, int status); 85 86 /** 87 * Initializes the FTL library. 88 * 89 * @return 0 on success, negative errno otherwise. 90 */ 91 int spdk_ftl_init(void); 92 93 /** 94 * Deinitializes the FTL library. 95 */ 96 void spdk_ftl_fini(void); 97 98 /** 99 * Initialize the FTL on the given pair of bdevs - base and cache bdev. 100 * Upon receiving a successful completion callback user is free to use I/O calls. 101 * 102 * \param conf configuration for new device 103 * \param cb callback function to call when the device is created 104 * \param cb_arg callback's argument 105 * 106 * \return 0 if initialization was started successfully, negative errno otherwise. 107 */ 108 int spdk_ftl_dev_init(const struct spdk_ftl_conf *conf, spdk_ftl_init_fn cb, void *cb_arg); 109 110 /** 111 * Deinitialize and free given device. 112 * 113 * \param dev device 114 * \param cb callback function to call when the device is freed 115 * \param cb_arg callback's argument 116 * 117 * \return 0 if deinitialization was started successfully, negative errno otherwise. 118 */ 119 int spdk_ftl_dev_free(struct spdk_ftl_dev *dev, spdk_ftl_fn cb, void *cb_arg); 120 121 /** 122 * Retrieve device’s attributes. 123 * 124 * \param dev device 125 * \param attr Attribute structure to fill 126 */ 127 void spdk_ftl_dev_get_attrs(const struct spdk_ftl_dev *dev, struct spdk_ftl_attrs *attr); 128 129 /** 130 * Retrieve device’s configuration. 131 * 132 * \param dev device 133 * \param conf FTL configuration structure to fill 134 */ 135 void spdk_ftl_dev_get_conf(const struct spdk_ftl_dev *dev, struct spdk_ftl_conf *conf); 136 137 /** 138 * Obtain an I/O channel for the device. 139 * 140 * \param dev device 141 * 142 * \return A handle to the I/O channel or NULL on failure. 143 */ 144 struct spdk_io_channel *spdk_ftl_get_io_channel(struct spdk_ftl_dev *dev); 145 146 /** 147 * Make a deep copy of an FTL configuration structure 148 * 149 * \param dst The destination FTL configuration 150 * \param src The source FTL configuration 151 */ 152 int spdk_ftl_conf_copy(struct spdk_ftl_conf *dst, const struct spdk_ftl_conf *src); 153 154 /** 155 * Release the FTL configuration resources. This does not free the structure itself. 156 * 157 * \param conf FTL configuration to deinitialize 158 */ 159 void spdk_ftl_conf_deinit(struct spdk_ftl_conf *conf); 160 161 /** 162 * Initialize FTL configuration structure with default values. 163 * 164 * \param conf FTL configuration to initialize 165 */ 166 void spdk_ftl_get_default_conf(struct spdk_ftl_conf *conf); 167 168 /** 169 * Submits a read to the specified device. 170 * 171 * \param dev Device 172 * \param io Allocated ftl_io 173 * \param ch I/O channel 174 * \param lba Starting LBA to read the data 175 * \param lba_cnt Number of sectors to read 176 * \param iov Single IO vector or pointer to IO vector table 177 * \param iov_cnt Number of IO vectors 178 * \param cb_fn Callback function to invoke when the I/O is completed 179 * \param cb_arg Argument to pass to the callback function 180 * 181 * \return 0 if successfully submitted, negative errno otherwise. 182 */ 183 int spdk_ftl_readv(struct spdk_ftl_dev *dev, struct ftl_io *io, struct spdk_io_channel *ch, 184 uint64_t lba, uint64_t lba_cnt, 185 struct iovec *iov, size_t iov_cnt, spdk_ftl_fn cb_fn, void *cb_arg); 186 187 /** 188 * Submits a write to the specified device. 189 * 190 * \param dev Device 191 * \param io Allocated ftl_io 192 * \param ch I/O channel 193 * \param lba Starting LBA to write the data 194 * \param lba_cnt Number of sectors to write 195 * \param iov Single IO vector or pointer to IO vector table 196 * \param iov_cnt Number of IO vectors 197 * \param cb_fn Callback function to invoke when the I/O is completed 198 * \param cb_arg Argument to pass to the callback function 199 * 200 * \return 0 if successfully submitted, negative errno otherwise. 201 */ 202 int spdk_ftl_writev(struct spdk_ftl_dev *dev, struct ftl_io *io, struct spdk_io_channel *ch, 203 uint64_t lba, uint64_t lba_cnt, 204 struct iovec *iov, size_t iov_cnt, spdk_ftl_fn cb_fn, void *cb_arg); 205 206 /** 207 * Submits a unmap to the specified device. 208 * 209 * \param dev Device 210 * \param io Allocated ftl_io 211 * \param ch I/O channel 212 * \param lba Starting LBA to write the data 213 * \param lba_cnt Number of blocks to unmap 214 * \param cb_fn Callback function to invoke when the I/O is completed 215 * \param cb_arg Argument to pass to the callback function 216 * 217 * \return 0 if successfully submitted, negative errno otherwise. 218 */ 219 int spdk_ftl_unmap(struct spdk_ftl_dev *dev, struct ftl_io *io, struct spdk_io_channel *ch, 220 uint64_t lba, uint64_t lba_cnt, spdk_ftl_fn cb_fn, void *cb_arg); 221 222 /** 223 * Returns the size of ftl_io struct that needs to be passed to spdk_ftl_read/write 224 * 225 * \return The size of struct 226 */ 227 size_t spdk_ftl_io_size(void); 228 229 /** 230 * Enable fast shutdown. 231 * 232 * During fast shutdown FTL will keep the necessary metadata in shared memory instead 233 * of serializing it to storage. This allows for shorter downtime during upgrade process. 234 */ 235 void spdk_ftl_dev_set_fast_shutdown(struct spdk_ftl_dev *dev, bool fast_shutdown); 236 237 #ifdef __cplusplus 238 } 239 #endif 240 241 #endif /* SPDK_FTL_H */ 242