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