1 /*- 2 * BSD LICENSE 3 * 4 * Copyright (c) Intel Corporation. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * * Neither the name of Intel Corporation nor the names of its 18 * contributors may be used to endorse or promote products derived 19 * from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 */ 33 34 #include "spdk/stdinc.h" 35 36 #include "spdk/nvme.h" 37 #include "spdk/vmd.h" 38 #include "spdk/env.h" 39 40 struct ctrlr_entry { 41 struct spdk_nvme_ctrlr *ctrlr; 42 struct ctrlr_entry *next; 43 char name[1024]; 44 }; 45 46 struct ns_entry { 47 struct spdk_nvme_ctrlr *ctrlr; 48 struct spdk_nvme_ns *ns; 49 struct ns_entry *next; 50 struct spdk_nvme_qpair *qpair; 51 }; 52 53 static struct ctrlr_entry *g_controllers = NULL; 54 static struct ns_entry *g_namespaces = NULL; 55 56 static bool g_vmd = false; 57 58 static void 59 register_ns(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_ns *ns) 60 { 61 struct ns_entry *entry; 62 const struct spdk_nvme_ctrlr_data *cdata; 63 64 /* 65 * spdk_nvme_ctrlr is the logical abstraction in SPDK for an NVMe 66 * controller. During initialization, the IDENTIFY data for the 67 * controller is read using an NVMe admin command, and that data 68 * can be retrieved using spdk_nvme_ctrlr_get_data() to get 69 * detailed information on the controller. Refer to the NVMe 70 * specification for more details on IDENTIFY for NVMe controllers. 71 */ 72 cdata = spdk_nvme_ctrlr_get_data(ctrlr); 73 74 if (!spdk_nvme_ns_is_active(ns)) { 75 printf("Controller %-20.20s (%-20.20s): Skipping inactive NS %u\n", 76 cdata->mn, cdata->sn, 77 spdk_nvme_ns_get_id(ns)); 78 return; 79 } 80 81 entry = malloc(sizeof(struct ns_entry)); 82 if (entry == NULL) { 83 perror("ns_entry malloc"); 84 exit(1); 85 } 86 87 entry->ctrlr = ctrlr; 88 entry->ns = ns; 89 entry->next = g_namespaces; 90 g_namespaces = entry; 91 92 printf(" Namespace ID: %d size: %juGB\n", spdk_nvme_ns_get_id(ns), 93 spdk_nvme_ns_get_size(ns) / 1000000000); 94 } 95 96 struct hello_world_sequence { 97 struct ns_entry *ns_entry; 98 char *buf; 99 unsigned using_cmb_io; 100 int is_completed; 101 }; 102 103 static void 104 read_complete(void *arg, const struct spdk_nvme_cpl *completion) 105 { 106 struct hello_world_sequence *sequence = arg; 107 108 /* Assume the I/O was successful */ 109 sequence->is_completed = 1; 110 /* See if an error occurred. If so, display information 111 * about it, and set completion value so that I/O 112 * caller is aware that an error occurred. 113 */ 114 if (spdk_nvme_cpl_is_error(completion)) { 115 spdk_nvme_qpair_print_completion(sequence->ns_entry->qpair, (struct spdk_nvme_cpl *)completion); 116 fprintf(stderr, "I/O error status: %s\n", spdk_nvme_cpl_get_status_string(&completion->status)); 117 fprintf(stderr, "Read I/O failed, aborting run\n"); 118 sequence->is_completed = 2; 119 } 120 121 /* 122 * The read I/O has completed. Print the contents of the 123 * buffer, free the buffer, then mark the sequence as 124 * completed. This will trigger the hello_world() function 125 * to exit its polling loop. 126 */ 127 printf("%s", sequence->buf); 128 spdk_free(sequence->buf); 129 } 130 131 static void 132 write_complete(void *arg, const struct spdk_nvme_cpl *completion) 133 { 134 struct hello_world_sequence *sequence = arg; 135 struct ns_entry *ns_entry = sequence->ns_entry; 136 int rc; 137 138 /* See if an error occurred. If so, display information 139 * about it, and set completion value so that I/O 140 * caller is aware that an error occurred. 141 */ 142 if (spdk_nvme_cpl_is_error(completion)) { 143 spdk_nvme_qpair_print_completion(sequence->ns_entry->qpair, (struct spdk_nvme_cpl *)completion); 144 fprintf(stderr, "I/O error status: %s\n", spdk_nvme_cpl_get_status_string(&completion->status)); 145 fprintf(stderr, "Write I/O failed, aborting run\n"); 146 sequence->is_completed = 2; 147 exit(1); 148 } 149 /* 150 * The write I/O has completed. Free the buffer associated with 151 * the write I/O and allocate a new zeroed buffer for reading 152 * the data back from the NVMe namespace. 153 */ 154 if (sequence->using_cmb_io) { 155 spdk_nvme_ctrlr_free_cmb_io_buffer(ns_entry->ctrlr, sequence->buf, 0x1000); 156 } else { 157 spdk_free(sequence->buf); 158 } 159 sequence->buf = spdk_zmalloc(0x1000, 0x1000, NULL, SPDK_ENV_SOCKET_ID_ANY, SPDK_MALLOC_DMA); 160 161 rc = spdk_nvme_ns_cmd_read(ns_entry->ns, ns_entry->qpair, sequence->buf, 162 0, /* LBA start */ 163 1, /* number of LBAs */ 164 read_complete, (void *)sequence, 0); 165 if (rc != 0) { 166 fprintf(stderr, "starting read I/O failed\n"); 167 exit(1); 168 } 169 } 170 171 static void 172 hello_world(void) 173 { 174 struct ns_entry *ns_entry; 175 struct hello_world_sequence sequence; 176 int rc; 177 178 ns_entry = g_namespaces; 179 while (ns_entry != NULL) { 180 /* 181 * Allocate an I/O qpair that we can use to submit read/write requests 182 * to namespaces on the controller. NVMe controllers typically support 183 * many qpairs per controller. Any I/O qpair allocated for a controller 184 * can submit I/O to any namespace on that controller. 185 * 186 * The SPDK NVMe driver provides no synchronization for qpair accesses - 187 * the application must ensure only a single thread submits I/O to a 188 * qpair, and that same thread must also check for completions on that 189 * qpair. This enables extremely efficient I/O processing by making all 190 * I/O operations completely lockless. 191 */ 192 ns_entry->qpair = spdk_nvme_ctrlr_alloc_io_qpair(ns_entry->ctrlr, NULL, 0); 193 if (ns_entry->qpair == NULL) { 194 printf("ERROR: spdk_nvme_ctrlr_alloc_io_qpair() failed\n"); 195 return; 196 } 197 198 /* 199 * Use spdk_dma_zmalloc to allocate a 4KB zeroed buffer. This memory 200 * will be pinned, which is required for data buffers used for SPDK NVMe 201 * I/O operations. 202 */ 203 sequence.using_cmb_io = 1; 204 sequence.buf = spdk_nvme_ctrlr_alloc_cmb_io_buffer(ns_entry->ctrlr, 0x1000); 205 if (sequence.buf == NULL) { 206 sequence.using_cmb_io = 0; 207 sequence.buf = spdk_zmalloc(0x1000, 0x1000, NULL, SPDK_ENV_SOCKET_ID_ANY, SPDK_MALLOC_DMA); 208 } 209 if (sequence.buf == NULL) { 210 printf("ERROR: write buffer allocation failed\n"); 211 return; 212 } 213 if (sequence.using_cmb_io) { 214 printf("INFO: using controller memory buffer for IO\n"); 215 } else { 216 printf("INFO: using host memory buffer for IO\n"); 217 } 218 sequence.is_completed = 0; 219 sequence.ns_entry = ns_entry; 220 221 /* 222 * Print "Hello world!" to sequence.buf. We will write this data to LBA 223 * 0 on the namespace, and then later read it back into a separate buffer 224 * to demonstrate the full I/O path. 225 */ 226 snprintf(sequence.buf, 0x1000, "%s", "Hello world!\n"); 227 228 /* 229 * Write the data buffer to LBA 0 of this namespace. "write_complete" and 230 * "&sequence" are specified as the completion callback function and 231 * argument respectively. write_complete() will be called with the 232 * value of &sequence as a parameter when the write I/O is completed. 233 * This allows users to potentially specify different completion 234 * callback routines for each I/O, as well as pass a unique handle 235 * as an argument so the application knows which I/O has completed. 236 * 237 * Note that the SPDK NVMe driver will only check for completions 238 * when the application calls spdk_nvme_qpair_process_completions(). 239 * It is the responsibility of the application to trigger the polling 240 * process. 241 */ 242 rc = spdk_nvme_ns_cmd_write(ns_entry->ns, ns_entry->qpair, sequence.buf, 243 0, /* LBA start */ 244 1, /* number of LBAs */ 245 write_complete, &sequence, 0); 246 if (rc != 0) { 247 fprintf(stderr, "starting write I/O failed\n"); 248 exit(1); 249 } 250 251 /* 252 * Poll for completions. 0 here means process all available completions. 253 * In certain usage models, the caller may specify a positive integer 254 * instead of 0 to signify the maximum number of completions it should 255 * process. This function will never block - if there are no 256 * completions pending on the specified qpair, it will return immediately. 257 * 258 * When the write I/O completes, write_complete() will submit a new I/O 259 * to read LBA 0 into a separate buffer, specifying read_complete() as its 260 * completion routine. When the read I/O completes, read_complete() will 261 * print the buffer contents and set sequence.is_completed = 1. That will 262 * break this loop and then exit the program. 263 */ 264 while (!sequence.is_completed) { 265 spdk_nvme_qpair_process_completions(ns_entry->qpair, 0); 266 } 267 268 /* 269 * Free the I/O qpair. This typically is done when an application exits. 270 * But SPDK does support freeing and then reallocating qpairs during 271 * operation. It is the responsibility of the caller to ensure all 272 * pending I/O are completed before trying to free the qpair. 273 */ 274 spdk_nvme_ctrlr_free_io_qpair(ns_entry->qpair); 275 ns_entry = ns_entry->next; 276 } 277 } 278 279 static bool 280 probe_cb(void *cb_ctx, const struct spdk_nvme_transport_id *trid, 281 struct spdk_nvme_ctrlr_opts *opts) 282 { 283 printf("Attaching to %s\n", trid->traddr); 284 285 return true; 286 } 287 288 static void 289 attach_cb(void *cb_ctx, const struct spdk_nvme_transport_id *trid, 290 struct spdk_nvme_ctrlr *ctrlr, const struct spdk_nvme_ctrlr_opts *opts) 291 { 292 int nsid, num_ns; 293 struct ctrlr_entry *entry; 294 struct spdk_nvme_ns *ns; 295 const struct spdk_nvme_ctrlr_data *cdata = spdk_nvme_ctrlr_get_data(ctrlr); 296 297 entry = malloc(sizeof(struct ctrlr_entry)); 298 if (entry == NULL) { 299 perror("ctrlr_entry malloc"); 300 exit(1); 301 } 302 303 printf("Attached to %s\n", trid->traddr); 304 305 snprintf(entry->name, sizeof(entry->name), "%-20.20s (%-20.20s)", cdata->mn, cdata->sn); 306 307 entry->ctrlr = ctrlr; 308 entry->next = g_controllers; 309 g_controllers = entry; 310 311 /* 312 * Each controller has one or more namespaces. An NVMe namespace is basically 313 * equivalent to a SCSI LUN. The controller's IDENTIFY data tells us how 314 * many namespaces exist on the controller. For Intel(R) P3X00 controllers, 315 * it will just be one namespace. 316 * 317 * Note that in NVMe, namespace IDs start at 1, not 0. 318 */ 319 num_ns = spdk_nvme_ctrlr_get_num_ns(ctrlr); 320 printf("Using controller %s with %d namespaces.\n", entry->name, num_ns); 321 for (nsid = 1; nsid <= num_ns; nsid++) { 322 ns = spdk_nvme_ctrlr_get_ns(ctrlr, nsid); 323 if (ns == NULL) { 324 continue; 325 } 326 register_ns(ctrlr, ns); 327 } 328 } 329 330 static void 331 cleanup(void) 332 { 333 struct ns_entry *ns_entry = g_namespaces; 334 struct ctrlr_entry *ctrlr_entry = g_controllers; 335 336 while (ns_entry) { 337 struct ns_entry *next = ns_entry->next; 338 free(ns_entry); 339 ns_entry = next; 340 } 341 342 while (ctrlr_entry) { 343 struct ctrlr_entry *next = ctrlr_entry->next; 344 345 spdk_nvme_detach(ctrlr_entry->ctrlr); 346 free(ctrlr_entry); 347 ctrlr_entry = next; 348 } 349 } 350 351 static void 352 usage(const char *program_name) 353 { 354 printf("%s [options]", program_name); 355 printf("\n"); 356 printf("options:\n"); 357 printf(" -V enumerate VMD\n"); 358 } 359 360 static int 361 parse_args(int argc, char **argv) 362 { 363 int op; 364 365 while ((op = getopt(argc, argv, "V")) != -1) { 366 switch (op) { 367 case 'V': 368 g_vmd = true; 369 break; 370 default: 371 usage(argv[0]); 372 return 1; 373 } 374 } 375 376 return 0; 377 } 378 379 int main(int argc, char **argv) 380 { 381 int rc; 382 struct spdk_env_opts opts; 383 384 rc = parse_args(argc, argv); 385 if (rc != 0) { 386 return rc; 387 } 388 389 /* 390 * SPDK relies on an abstraction around the local environment 391 * named env that handles memory allocation and PCI device operations. 392 * This library must be initialized first. 393 * 394 */ 395 spdk_env_opts_init(&opts); 396 opts.name = "hello_world"; 397 opts.shm_id = 0; 398 if (spdk_env_init(&opts) < 0) { 399 fprintf(stderr, "Unable to initialize SPDK env\n"); 400 return 1; 401 } 402 403 printf("Initializing NVMe Controllers\n"); 404 405 if (g_vmd && spdk_vmd_init()) { 406 fprintf(stderr, "Failed to initialize VMD." 407 " Some NVMe devices can be unavailable.\n"); 408 } 409 410 /* 411 * Start the SPDK NVMe enumeration process. probe_cb will be called 412 * for each NVMe controller found, giving our application a choice on 413 * whether to attach to each controller. attach_cb will then be 414 * called for each controller after the SPDK NVMe driver has completed 415 * initializing the controller we chose to attach. 416 */ 417 rc = spdk_nvme_probe(NULL, NULL, probe_cb, attach_cb, NULL); 418 if (rc != 0) { 419 fprintf(stderr, "spdk_nvme_probe() failed\n"); 420 cleanup(); 421 return 1; 422 } 423 424 if (g_controllers == NULL) { 425 fprintf(stderr, "no NVMe controllers found\n"); 426 cleanup(); 427 return 1; 428 } 429 430 printf("Initialization complete.\n"); 431 hello_world(); 432 cleanup(); 433 return 0; 434 } 435