1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (c) 2020, Western Digital Corporation. All rights reserved. 3 */ 4 5 /** 6 * \file 7 * NVMe driver public API extension for Zoned Namespace Command Set 8 */ 9 10 #ifndef SPDK_NVME_ZNS_H 11 #define SPDK_NVME_ZNS_H 12 13 #include "spdk/stdinc.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 #include "spdk/nvme.h" 20 21 /** 22 * Get the Zoned Namespace Command Set Specific Identify Namespace data 23 * as defined by the NVMe Zoned Namespace Command Set Specification. 24 * 25 * This function is thread safe and can be called at any point while the controller 26 * is attached to the SPDK NVMe driver. 27 * 28 * \param ns Namespace. 29 * 30 * \return a pointer to the namespace data, or NULL if the namespace is not 31 * a Zoned Namespace. 32 */ 33 const struct spdk_nvme_zns_ns_data *spdk_nvme_zns_ns_get_data(struct spdk_nvme_ns *ns); 34 35 /** 36 * Get the zone size, in number of sectors, of the given namespace. 37 * 38 * This function is thread safe and can be called at any point while the controller 39 * is attached to the SPDK NVMe driver. 40 * 41 * \param ns Namespace to query. 42 * 43 * \return the zone size of the given namespace in number of sectors. 44 */ 45 uint64_t spdk_nvme_zns_ns_get_zone_size_sectors(struct spdk_nvme_ns *ns); 46 47 /** 48 * Get the zone size, in bytes, of the given namespace. 49 * 50 * This function is thread safe and can be called at any point while the controller 51 * is attached to the SPDK NVMe driver. 52 * 53 * \param ns Namespace to query. 54 * 55 * \return the zone size of the given namespace in bytes. 56 */ 57 uint64_t spdk_nvme_zns_ns_get_zone_size(struct spdk_nvme_ns *ns); 58 59 /** 60 * Get the number of zones for the given namespace. 61 * 62 * This function is thread safe and can be called at any point while the controller 63 * is attached to the SPDK NVMe driver. 64 * 65 * \param ns Namespace to query. 66 * 67 * \return the number of zones. 68 */ 69 uint64_t spdk_nvme_zns_ns_get_num_zones(struct spdk_nvme_ns *ns); 70 71 /** 72 * Get the maximum number of open zones for the given namespace. 73 * 74 * An open zone is a zone in any of the zone states: 75 * EXPLICIT OPEN or IMPLICIT OPEN. 76 * 77 * If this value is 0, there is no limit. 78 * 79 * This function is thread safe and can be called at any point while the controller 80 * is attached to the SPDK NVMe driver. 81 * 82 * \param ns Namespace to query. 83 * 84 * \return the maximum number of open zones. 85 */ 86 uint32_t spdk_nvme_zns_ns_get_max_open_zones(struct spdk_nvme_ns *ns); 87 88 /** 89 * Get the maximum number of active zones for the given namespace. 90 * 91 * An active zone is a zone in any of the zone states: 92 * EXPLICIT OPEN, IMPLICIT OPEN or CLOSED. 93 * 94 * If this value is 0, there is no limit. 95 * 96 * This function is thread safe and can be called at any point while the controller 97 * is attached to the SPDK NVMe driver. 98 * 99 * \param ns Namespace to query. 100 * 101 * \return the maximum number of active zones. 102 */ 103 uint32_t spdk_nvme_zns_ns_get_max_active_zones(struct spdk_nvme_ns *ns); 104 105 /** 106 * Get the Zoned Namespace Command Set Specific Identify Controller data 107 * as defined by the NVMe Zoned Namespace Command Set Specification. 108 * 109 * This function is thread safe and can be called at any point while the controller 110 * is attached to the SPDK NVMe driver. 111 * 112 * \param ctrlr Opaque handle to NVMe controller. 113 * 114 * \return pointer to the controller data, or NULL if the controller does not 115 * support the Zoned Command Set. 116 */ 117 const struct spdk_nvme_zns_ctrlr_data *spdk_nvme_zns_ctrlr_get_data(struct spdk_nvme_ctrlr *ctrlr); 118 119 /** 120 * Get the maximum zone append data transfer size of a given NVMe controller. 121 * 122 * \param ctrlr Opaque handle to NVMe controller. 123 * 124 * \return Maximum zone append data transfer size of the NVMe controller in bytes. 125 */ 126 uint32_t spdk_nvme_zns_ctrlr_get_max_zone_append_size(const struct spdk_nvme_ctrlr *ctrlr); 127 128 /** 129 * Submit a zone append I/O to the specified NVMe namespace. 130 * 131 * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). 132 * The user must ensure that only one thread submits I/O on a given qpair at any 133 * given time. 134 * 135 * \param ns NVMe namespace to submit the zone append I/O. 136 * \param qpair I/O queue pair to submit the request. 137 * \param buffer Virtual address pointer to the data payload buffer. 138 * \param zslba Zone Start LBA of the zone that we are appending to. 139 * \param lba_count Length (in sectors) for the zone append operation. 140 * \param cb_fn Callback function to invoke when the I/O is completed. 141 * \param cb_arg Argument to pass to the callback function. 142 * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in 143 * spdk/nvme_spec.h, for this I/O. 144 * 145 * \return 0 if successfully submitted, negated errnos on the following error conditions: 146 * -EINVAL: The request is malformed. 147 * -ENOMEM: The request cannot be allocated. 148 * -ENXIO: The qpair is failed at the transport level. 149 */ 150 int spdk_nvme_zns_zone_append(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 151 void *buffer, uint64_t zslba, 152 uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, 153 uint32_t io_flags); 154 155 /** 156 * Submit a zone append I/O to the specified NVMe namespace. 157 * 158 * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). 159 * The user must ensure that only one thread submits I/O on a given qpair at any 160 * given time. 161 * 162 * \param ns NVMe namespace to submit the zone append I/O. 163 * \param qpair I/O queue pair to submit the request. 164 * \param buffer Virtual address pointer to the data payload buffer. 165 * \param metadata Virtual address pointer to the metadata payload, the length 166 * of metadata is specified by spdk_nvme_ns_get_md_size(). 167 * \param zslba Zone Start LBA of the zone that we are appending to. 168 * \param lba_count Length (in sectors) for the zone append operation. 169 * \param cb_fn Callback function to invoke when the I/O is completed. 170 * \param cb_arg Argument to pass to the callback function. 171 * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in 172 * spdk/nvme_spec.h, for this I/O. 173 * \param apptag_mask Application tag mask. 174 * \param apptag Application tag to use end-to-end protection information. 175 * 176 * \return 0 if successfully submitted, negated errnos on the following error conditions: 177 * -EINVAL: The request is malformed. 178 * -ENOMEM: The request cannot be allocated. 179 * -ENXIO: The qpair is failed at the transport level. 180 */ 181 int spdk_nvme_zns_zone_append_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 182 void *buffer, void *metadata, uint64_t zslba, 183 uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, 184 uint32_t io_flags, uint16_t apptag_mask, uint16_t apptag); 185 186 /** 187 * Submit a zone append I/O to the specified NVMe namespace. 188 * 189 * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). 190 * The user must ensure that only one thread submits I/O on a given qpair at any 191 * given time. 192 * 193 * \param ns NVMe namespace to submit the zone append I/O. 194 * \param qpair I/O queue pair to submit the request. 195 * \param zslba Zone Start LBA of the zone that we are appending to. 196 * \param lba_count Length (in sectors) for the zone append operation. 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 * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. 200 * \param reset_sgl_fn Callback function to reset scattered payload. 201 * \param next_sge_fn Callback function to iterate each scattered payload memory 202 * segment. 203 * 204 * \return 0 if successfully submitted, negated errnos on the following error conditions: 205 * -EINVAL: The request is malformed. 206 * -ENOMEM: The request cannot be allocated. 207 * -ENXIO: The qpair is failed at the transport level. 208 */ 209 int spdk_nvme_zns_zone_appendv(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 210 uint64_t zslba, uint32_t lba_count, 211 spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, 212 spdk_nvme_req_reset_sgl_cb reset_sgl_fn, 213 spdk_nvme_req_next_sge_cb next_sge_fn); 214 215 /** 216 * Submit a zone append I/O to the specified NVMe namespace. 217 * 218 * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). 219 * The user must ensure that only one thread submits I/O on a given qpair at any 220 * given time. 221 * 222 * \param ns NVMe namespace to submit the zone append I/O. 223 * \param qpair I/O queue pair to submit the request. 224 * \param zslba Zone Start LBA of the zone that we are appending to. 225 * \param lba_count Length (in sectors) for the zone append operation. 226 * \param cb_fn Callback function to invoke when the I/O is completed. 227 * \param cb_arg Argument to pass to the callback function. 228 * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. 229 * \param reset_sgl_fn Callback function to reset scattered payload. 230 * \param next_sge_fn Callback function to iterate each scattered payload memory 231 * segment. 232 * \param metadata Virtual address pointer to the metadata payload, the length 233 * of metadata is specified by spdk_nvme_ns_get_md_size(). 234 * \param apptag_mask Application tag mask. 235 * \param apptag Application tag to use end-to-end protection information. 236 * 237 * \return 0 if successfully submitted, negated errnos on the following error conditions: 238 * -EINVAL: The request is malformed. 239 * -ENOMEM: The request cannot be allocated. 240 * -ENXIO: The qpair is failed at the transport level. 241 */ 242 int spdk_nvme_zns_zone_appendv_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 243 uint64_t zslba, uint32_t lba_count, 244 spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, 245 spdk_nvme_req_reset_sgl_cb reset_sgl_fn, 246 spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata, 247 uint16_t apptag_mask, uint16_t apptag); 248 249 /** 250 * Submit a Close Zone operation to the specified NVMe namespace. 251 * 252 * \param ns Namespace. 253 * \param qpair I/O queue pair to submit the request. 254 * \param slba starting LBA of the zone to operate on. 255 * \param select_all If this is set, slba will be ignored, and operation will 256 * be performed on all zones that are in ZSIO or ZSEO state. 257 * \param cb_fn Callback function invoked when the I/O command completes. 258 * \param cb_arg Argument passed to callback function. 259 * 260 * \return 0 on success. Negated errno on failure. 261 */ 262 int spdk_nvme_zns_close_zone(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 263 uint64_t slba, bool select_all, 264 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 265 266 /** 267 * Submit a Finish Zone operation to the specified NVMe namespace. 268 * 269 * \param ns Namespace. 270 * \param qpair I/O queue pair to submit the request. 271 * \param slba starting LBA of the zone to operate on. 272 * \param select_all If this is set, slba will be ignored, and operation will 273 * be performed on all zones that are in ZSIO, ZSEO, or ZSC state. 274 * \param cb_fn Callback function invoked when the I/O command completes. 275 * \param cb_arg Argument passed to callback function. 276 * 277 * \return 0 on success. Negated errno on failure. 278 */ 279 int spdk_nvme_zns_finish_zone(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 280 uint64_t slba, bool select_all, 281 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 282 283 /** 284 * Submit a Open Zone operation to the specified NVMe namespace. 285 * 286 * \param ns Namespace. 287 * \param qpair I/O queue pair to submit the request. 288 * \param slba starting LBA of the zone to operate on. 289 * \param select_all If this is set, slba will be ignored, and operation will 290 * be performed on all zones that are in ZSC state. 291 * \param cb_fn Callback function invoked when the I/O command completes. 292 * \param cb_arg Argument passed to callback function. 293 * 294 * \return 0 on success. Negated errno on failure. 295 */ 296 int spdk_nvme_zns_open_zone(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 297 uint64_t slba, bool select_all, 298 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 299 300 /** 301 * Submit a Reset Zone operation to the specified NVMe namespace. 302 * 303 * \param ns Namespace. 304 * \param qpair I/O queue pair to submit the request. 305 * \param slba starting LBA of the zone to operate on. 306 * \param select_all If this is set, slba will be ignored, and operation will 307 * be performed on all zones that are in ZSIO, ZSEO, ZSC, or ZSF state. 308 * \param cb_fn Callback function invoked when the I/O command completes. 309 * \param cb_arg Argument passed to callback function. 310 * 311 * \return 0 on success. Negated errno on failure. 312 */ 313 int spdk_nvme_zns_reset_zone(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 314 uint64_t slba, bool select_all, 315 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 316 317 /** 318 * Submit a Offline Zone operation to the specified NVMe namespace. 319 * 320 * \param ns Namespace. 321 * \param qpair I/O queue pair to submit the request. 322 * \param slba starting LBA of the zone to operate on. 323 * \param select_all If this is set, slba will be ignored, and operation will 324 * be performed on all zones that are in ZSRO state. 325 * \param cb_fn Callback function invoked when the I/O command completes. 326 * \param cb_arg Argument passed to callback function. 327 * 328 * \return 0 on success. Negated errno on failure. 329 */ 330 int spdk_nvme_zns_offline_zone(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 331 uint64_t slba, bool select_all, 332 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 333 334 /** 335 * Submit a Set Zone Descriptor Extension operation to the specified NVMe namespace. 336 * 337 * \param ns Namespace. 338 * \param qpair I/O queue pair to submit the request. 339 * \param slba starting LBA of the zone to operate on. 340 * \param buffer Virtual address pointer to the data payload buffer. 341 * \param payload_size Payload buffer size. 342 * \param cb_fn Callback function invoked when the I/O command completes. 343 * \param cb_arg Argument passed to callback function. 344 * 345 * \return 0 on success. Negated errno on failure. 346 */ 347 int spdk_nvme_zns_set_zone_desc_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 348 uint64_t slba, void *buffer, uint32_t payload_size, 349 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 350 351 /** 352 * Get a zone report from the specified NVMe namespace. 353 * 354 * \param ns Namespace. 355 * \param qpair I/O queue pair to submit the request. 356 * \param payload The pointer to the payload buffer. 357 * \param payload_size The size of payload buffer. 358 * \param slba starting LBA of the zone to operate on. 359 * \param report_opts Filter on which zone states to include in the zone report. 360 * \param partial_report If true, nr_zones field in the zone report indicates the number of zone 361 * descriptors that were successfully written to the zone report. If false, nr_zones field in the 362 * zone report indicates the number of zone descriptors that match the report_opts criteria. 363 * \param cb_fn Callback function invoked when the I/O command completes. 364 * \param cb_arg Argument passed to callback function. 365 * 366 * \return 0 on success. Negated errno on failure. 367 */ 368 int spdk_nvme_zns_report_zones(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 369 void *payload, uint32_t payload_size, uint64_t slba, 370 enum spdk_nvme_zns_zra_report_opts report_opts, bool partial_report, 371 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 372 373 /** 374 * Get a extended zone report from the specified NVMe namespace. 375 * 376 * \param ns Namespace. 377 * \param qpair I/O queue pair to submit the request. 378 * \param payload The pointer to the payload buffer. 379 * \param payload_size The size of payload buffer. 380 * \param slba starting LBA of the zone to operate on. 381 * \param report_opts Filter on which zone states to include in the extended zone report. 382 * \param partial_report If true, nr_zones field in the extended zone report indicates the number of zone 383 * descriptors that were successfully written to the extended zone report. If false, nr_zones field in the 384 * extended zone report indicates the number of zone descriptors that match the report_opts criteria. 385 * \param cb_fn Callback function invoked when the I/O command completes. 386 * \param cb_arg Argument passed to callback function. 387 * 388 * \return 0 on success. Negated errno on failure. 389 */ 390 int spdk_nvme_zns_ext_report_zones(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, 391 void *payload, uint32_t payload_size, uint64_t slba, 392 enum spdk_nvme_zns_zra_report_opts report_opts, bool partial_report, 393 spdk_nvme_cmd_cb cb_fn, void *cb_arg); 394 395 #ifdef __cplusplus 396 } 397 #endif 398 399 #endif 400