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 /** 35 * \file 36 * SCSI to bdev translation layer 37 */ 38 39 #ifndef SPDK_SCSI_H 40 #define SPDK_SCSI_H 41 42 #include "spdk/stdinc.h" 43 44 #include "spdk/bdev.h" 45 #include "spdk/queue.h" 46 47 #include "spdk_internal/trace_defs.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /* Defines for SPDK tracing framework */ 54 #define SPDK_SCSI_MAX_DEVS 1024 55 #define SPDK_SCSI_DEV_MAX_PORTS 4 56 #define SPDK_SCSI_DEV_MAX_NAME 255 57 58 #define SPDK_SCSI_PORT_MAX_NAME_LENGTH 255 59 #define SPDK_SCSI_MAX_TRANSPORT_ID_LENGTH 255 60 61 enum spdk_scsi_data_dir { 62 SPDK_SCSI_DIR_NONE = 0, 63 SPDK_SCSI_DIR_TO_DEV = 1, 64 SPDK_SCSI_DIR_FROM_DEV = 2, 65 }; 66 67 enum spdk_scsi_task_func { 68 SPDK_SCSI_TASK_FUNC_ABORT_TASK = 0, 69 SPDK_SCSI_TASK_FUNC_ABORT_TASK_SET, 70 SPDK_SCSI_TASK_FUNC_CLEAR_TASK_SET, 71 SPDK_SCSI_TASK_FUNC_LUN_RESET, 72 }; 73 74 /* 75 * SAM does not define the value for these service responses. Each transport 76 * (i.e. SAS, FC, iSCSI) will map these value to transport-specific codes, 77 * and may add their own. 78 */ 79 enum spdk_scsi_task_mgmt_resp { 80 SPDK_SCSI_TASK_MGMT_RESP_COMPLETE, 81 SPDK_SCSI_TASK_MGMT_RESP_SUCCESS, 82 SPDK_SCSI_TASK_MGMT_RESP_REJECT, 83 SPDK_SCSI_TASK_MGMT_RESP_INVALID_LUN, 84 SPDK_SCSI_TASK_MGMT_RESP_TARGET_FAILURE, 85 SPDK_SCSI_TASK_MGMT_RESP_REJECT_FUNC_NOT_SUPPORTED 86 }; 87 88 struct spdk_scsi_task; 89 typedef void (*spdk_scsi_task_cpl)(struct spdk_scsi_task *task); 90 typedef void (*spdk_scsi_task_free)(struct spdk_scsi_task *task); 91 92 struct spdk_scsi_task { 93 uint8_t status; 94 uint8_t function; /* task mgmt function */ 95 uint8_t response; /* task mgmt response */ 96 97 struct spdk_scsi_lun *lun; 98 struct spdk_scsi_port *target_port; 99 struct spdk_scsi_port *initiator_port; 100 101 spdk_scsi_task_cpl cpl_fn; 102 spdk_scsi_task_free free_fn; 103 104 uint32_t ref; 105 uint32_t transfer_len; 106 uint32_t dxfer_dir; 107 uint32_t length; 108 109 /** 110 * Amount of data actually transferred. Can be less than requested 111 * transfer_len - i.e. SCSI INQUIRY. 112 */ 113 uint32_t data_transferred; 114 115 uint64_t offset; 116 117 uint8_t *cdb; 118 119 /** 120 * \internal 121 * Size of internal buffer or zero when iov.iov_base is not internally managed. 122 */ 123 uint32_t alloc_len; 124 /** 125 * \internal 126 * iov is internal buffer. Use iovs to access elements of IO. 127 */ 128 struct iovec iov; 129 struct iovec *iovs; 130 uint16_t iovcnt; 131 132 uint8_t sense_data[32]; 133 size_t sense_data_len; 134 135 void *bdev_io; 136 137 TAILQ_ENTRY(spdk_scsi_task) scsi_link; 138 139 uint32_t abort_id; 140 struct spdk_bdev_io_wait_entry bdev_io_wait; 141 }; 142 143 struct spdk_scsi_port; 144 struct spdk_scsi_dev; 145 struct spdk_scsi_lun; 146 struct spdk_scsi_lun_desc; 147 148 typedef void (*spdk_scsi_lun_remove_cb_t)(struct spdk_scsi_lun *, void *); 149 typedef void (*spdk_scsi_dev_destruct_cb_t)(void *cb_arg, int rc); 150 151 /** 152 * Initialize SCSI layer. 153 * 154 * \return 0 on success, -1 on failure. 155 */ 156 int spdk_scsi_init(void); 157 158 /** 159 * Stop and clean the SCSI layer. 160 */ 161 void spdk_scsi_fini(void); 162 163 /** 164 * Get the LUN id of the given logical unit. 165 * 166 * \param lun Logical unit. 167 * 168 * \return LUN id of the logical unit. 169 */ 170 int spdk_scsi_lun_get_id(const struct spdk_scsi_lun *lun); 171 172 /** 173 * Get the name of the bdev associated with the given logical unit. 174 * 175 * \param lun Logical unit. 176 * 177 * \return the name of the bdev associated with the logical unit. 178 */ 179 const char *spdk_scsi_lun_get_bdev_name(const struct spdk_scsi_lun *lun); 180 181 /** 182 * Get the SCSI device associated with the given logical unit. 183 * 184 * \param lun Logical unit. 185 * 186 * \return the SCSI device associated with the logical unit. 187 */ 188 const struct spdk_scsi_dev *spdk_scsi_lun_get_dev(const struct spdk_scsi_lun *lun); 189 190 /** 191 * Check if the logical unit is hot removing. 192 * 193 * \param lun Logical unit 194 * 195 * \return true if removing, false otherwise. 196 */ 197 bool spdk_scsi_lun_is_removing(const struct spdk_scsi_lun *lun); 198 199 /** 200 * Get the name of the given SCSI device. 201 * 202 * \param dev SCSI device. 203 * 204 * \return the name of the SCSI device on success, or NULL on failure. 205 */ 206 const char *spdk_scsi_dev_get_name(const struct spdk_scsi_dev *dev); 207 208 /** 209 * Get the id of the given SCSI device. 210 * 211 * \param dev SCSI device. 212 * 213 * \return the id of the SCSI device. 214 */ 215 int spdk_scsi_dev_get_id(const struct spdk_scsi_dev *dev); 216 217 /** 218 * Get the logical unit of the given SCSI device whose id is lun_id. 219 * 220 * \param dev SCSI device. 221 * \param lun_id Id of the logical unit. 222 * 223 * \return the logical unit on success, or NULL on failure. 224 */ 225 struct spdk_scsi_lun *spdk_scsi_dev_get_lun(struct spdk_scsi_dev *dev, int lun_id); 226 227 /** 228 * Get the first logical unit of the given SCSI device. 229 * 230 * \param dev SCSI device. 231 * 232 * \return the first logical unit on success, or NULL if there is no logical unit. 233 */ 234 struct spdk_scsi_lun *spdk_scsi_dev_get_first_lun(struct spdk_scsi_dev *dev); 235 236 /** 237 * Get the next logical unit of a SCSI device. 238 * 239 * \param prev_lun Previous logical unit. 240 * 241 * \return the next logical unit of a SCSI device, or NULL if the prev_lun was the last. 242 */ 243 struct spdk_scsi_lun *spdk_scsi_dev_get_next_lun(struct spdk_scsi_lun *prev_lun); 244 245 /** 246 * Check whether the SCSI device has any pending task. 247 * 248 * \param dev SCSI device. 249 * \param initiator_port Check tasks only from the initiator if specified, or 250 * all all tasks otherwise. 251 * 252 * \return true if the SCSI device has any pending task, or false otherwise. 253 */ 254 bool spdk_scsi_dev_has_pending_tasks(const struct spdk_scsi_dev *dev, 255 const struct spdk_scsi_port *initiator_port); 256 257 /** 258 * Destruct the SCSI device. 259 * 260 * \param dev SCSI device. 261 * \param cb_fn Callback function. 262 * \param cb_arg Argument to callback function. 263 */ 264 void spdk_scsi_dev_destruct(struct spdk_scsi_dev *dev, 265 spdk_scsi_dev_destruct_cb_t cb_fn, void *cb_arg); 266 267 /** 268 * Execute the SCSI management task. 269 * 270 * The task can be constructed by the function spdk_scsi_task_construct(). 271 * Code of task management function to be executed is set before calling this API. 272 * 273 * \param dev SCSI device. 274 * \param task SCSI task to be executed. 275 */ 276 void spdk_scsi_dev_queue_mgmt_task(struct spdk_scsi_dev *dev, struct spdk_scsi_task *task); 277 278 /** 279 * Execute the SCSI task. 280 * 281 * The task can be constructed by the function spdk_scsi_task_construct(). 282 * 283 * \param dev SCSI device. 284 * \param task Task to be executed. 285 */ 286 void spdk_scsi_dev_queue_task(struct spdk_scsi_dev *dev, struct spdk_scsi_task *task); 287 288 /** 289 * Add a new port to the given SCSI device. 290 * 291 * \param dev SCSI device. 292 * \param id Port id. 293 * \param name Port name. 294 * 295 * \return 0 on success, -1 on failure. 296 */ 297 int spdk_scsi_dev_add_port(struct spdk_scsi_dev *dev, uint64_t id, const char *name); 298 299 /** 300 * Delete a specified port of the given SCSI device. 301 * 302 * \param dev SCSI device. 303 * \param id Port id. 304 * 305 * \return 0 on success, -1 on failure. 306 */ 307 int spdk_scsi_dev_delete_port(struct spdk_scsi_dev *dev, uint64_t id); 308 309 /** 310 * Get the port of the given SCSI device whose port ID is id. 311 * 312 * \param dev SCSI device. 313 * \param id Port id. 314 * 315 * \return the port of the SCSI device on success, or NULL on failure. 316 */ 317 struct spdk_scsi_port *spdk_scsi_dev_find_port_by_id(struct spdk_scsi_dev *dev, uint64_t id); 318 319 /** 320 * Allocate I/O channels for all LUNs of the given SCSI device. 321 * 322 * \param dev SCSI device. 323 * 324 * \return 0 on success, -1 on failure. 325 */ 326 int spdk_scsi_dev_allocate_io_channels(struct spdk_scsi_dev *dev); 327 328 /** 329 * Free I/O channels from all LUNs of the given SCSI device. 330 */ 331 void spdk_scsi_dev_free_io_channels(struct spdk_scsi_dev *dev); 332 333 /** 334 * Construct a SCSI device object using the given parameters. 335 * 336 * \param name Name for the SCSI device. 337 * \param bdev_name_list List of bdev names to attach to the LUNs for this SCSI 338 * device. 339 * \param lun_id_list List of LUN IDs for the LUN in this SCSI device. Caller is 340 * responsible for managing the memory containing this list. lun_id_list[x] is 341 * the LUN ID for lun_list[x]. 342 * \param num_luns Number of entries in lun_list and lun_id_list. 343 * \param protocol_id SCSI SPC protocol identifier to report in INQUIRY data 344 * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove 345 * is first triggered. 346 * \param hotremove_ctx Additional argument to hotremove_cb. 347 * 348 * \return the constructed spdk_scsi_dev object. 349 */ 350 struct spdk_scsi_dev *spdk_scsi_dev_construct(const char *name, 351 const char *bdev_name_list[], 352 int *lun_id_list, 353 int num_luns, 354 uint8_t protocol_id, 355 void (*hotremove_cb)(const struct spdk_scsi_lun *, void *), 356 void *hotremove_ctx); 357 358 /** 359 * Construct a SCSI device object using the more given parameters. 360 * 361 * \param name Name for the SCSI device. 362 * \param bdev_name_list List of bdev names to attach to the LUNs for this SCSI 363 * device. 364 * \param lun_id_list List of LUN IDs for the LUN in this SCSI device. Caller is 365 * responsible for managing the memory containing this list. lun_id_list[x] is 366 * the LUN ID for lun_list[x]. 367 * \param num_luns Number of entries in lun_list and lun_id_list. 368 * \param protocol_id SCSI SPC protocol identifier to report in INQUIRY data 369 * \param resize_cb Callback of lun resize. 370 * \param resize_ctx Additional argument to resize_cb. 371 * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove 372 * is first triggered. 373 * \param hotremove_ctx Additional argument to hotremove_cb. 374 * 375 * \return the constructed spdk_scsi_dev object. 376 */ 377 struct spdk_scsi_dev *spdk_scsi_dev_construct_ext(const char *name, 378 const char *bdev_name_list[], 379 int *lun_id_list, 380 int num_luns, 381 uint8_t protocol_id, 382 void (*resize_cb)(const struct spdk_scsi_lun *, void *), 383 void *resize_ctx, 384 void (*hotremove_cb)(const struct spdk_scsi_lun *, void *), 385 void *hotremove_ctx); 386 387 /** 388 * Delete a logical unit of the given SCSI device. 389 * 390 * \param dev SCSI device. 391 * \param lun Logical unit to delete. 392 */ 393 void spdk_scsi_dev_delete_lun(struct spdk_scsi_dev *dev, struct spdk_scsi_lun *lun); 394 395 /** 396 * Add a new logical unit to the given SCSI device. 397 * 398 * \param dev SCSI device. 399 * \param bdev_name Name of the bdev attached to the logical unit. 400 * \param lun_id LUN id for the new logical unit. 401 * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove 402 * is first triggered. 403 * \param hotremove_ctx Additional argument to hotremove_cb. 404 */ 405 int spdk_scsi_dev_add_lun(struct spdk_scsi_dev *dev, const char *bdev_name, int lun_id, 406 void (*hotremove_cb)(const struct spdk_scsi_lun *, void *), 407 void *hotremove_ctx); 408 409 /** 410 * Add a new logical unit to the given SCSI device with more callbacks. 411 * 412 * \param dev SCSI device. 413 * \param bdev_name Name of the bdev attached to the logical unit. 414 * \param lun_id LUN id for the new logical unit. 415 * \param resize_cb Callback of lun resize. 416 * \param resize_ctx Additional argument to resize_cb. 417 * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove 418 * is first triggered. 419 * \param hotremove_ctx Additional argument to hotremove_cb. 420 */ 421 int spdk_scsi_dev_add_lun_ext(struct spdk_scsi_dev *dev, const char *bdev_name, int lun_id, 422 void (*resize_cb)(const struct spdk_scsi_lun *, void *), 423 void *resize_ctx, 424 void (*hotremove_cb)(const struct spdk_scsi_lun *, void *), 425 void *hotremove_ctx); 426 427 /** 428 * Create a new SCSI port. 429 * 430 * \param id Port id. 431 * \param index Port index. 432 * \param name Port Name. 433 * 434 * \return a pointer to the created SCSI port on success, or NULL on failure. 435 */ 436 struct spdk_scsi_port *spdk_scsi_port_create(uint64_t id, uint16_t index, const char *name); 437 438 /** 439 * Free the SCSI port. 440 * 441 * \param pport SCSI port to free. 442 */ 443 void spdk_scsi_port_free(struct spdk_scsi_port **pport); 444 445 /** 446 * Get the name of the SCSI port. 447 * 448 * \param port SCSI port to query. 449 * 450 * \return the name of the SCSI port. 451 */ 452 const char *spdk_scsi_port_get_name(const struct spdk_scsi_port *port); 453 454 /** 455 * Construct a new SCSI task. 456 * 457 * \param task SCSI task to construct. 458 * \param cpl_fn Called when the task is completed. 459 * \param free_fn Called when the task is freed 460 */ 461 void spdk_scsi_task_construct(struct spdk_scsi_task *task, 462 spdk_scsi_task_cpl cpl_fn, 463 spdk_scsi_task_free free_fn); 464 465 /** 466 * Put the SCSI task. 467 * 468 * \param task SCSI task to put. 469 */ 470 void spdk_scsi_task_put(struct spdk_scsi_task *task); 471 472 /** 473 * Set internal buffer to given one. Caller is owner of that buffer. 474 * 475 * \param task SCSI task. 476 * \param data Pointer to buffer. 477 * \param len Buffer length. 478 */ 479 void spdk_scsi_task_set_data(struct spdk_scsi_task *task, void *data, uint32_t len); 480 481 /** 482 * Single buffer -> vector of buffers. 483 * 484 * \param task SCSI task. 485 * \param src A pointer to the data buffer read from. 486 * \param len Length of the data buffer read from. 487 * 488 * \return the total length of the vector of buffers written into on success, or 489 * -1 on failure. 490 */ 491 int spdk_scsi_task_scatter_data(struct spdk_scsi_task *task, const void *src, size_t len); 492 493 /** 494 * Vector of buffers -> single buffer. 495 * 496 * \param task SCSI task, 497 * \param len Length of the buffer allocated and written into. 498 * 499 * \return a pointer to the buffer allocated and written into. 500 */ 501 void *spdk_scsi_task_gather_data(struct spdk_scsi_task *task, int *len); 502 503 /** 504 * Build sense data for the SCSI task. 505 * 506 * \param task SCSI task. 507 * \param sk Sense key. 508 * \param asc Additional sense code. 509 * \param ascq Additional sense code qualifier. 510 */ 511 void spdk_scsi_task_build_sense_data(struct spdk_scsi_task *task, int sk, int asc, 512 int ascq); 513 514 /** 515 * Set SCSI status code to the SCSI task. When the status code is CHECK CONDITION, 516 * sense data is build too. 517 * 518 * \param task SCSI task. 519 * \param sc Sense code 520 * \param sk Sense key. 521 * \param asc Additional sense code. 522 * \param ascq Additional sense code qualifier. 523 */ 524 void spdk_scsi_task_set_status(struct spdk_scsi_task *task, int sc, int sk, int asc, 525 int ascq); 526 527 /** 528 * Copy SCSI status. 529 * 530 * \param dst SCSI task whose status is written to. 531 * \param src SCSI task whose status is read from. 532 */ 533 void spdk_scsi_task_copy_status(struct spdk_scsi_task *dst, struct spdk_scsi_task *src); 534 535 /** 536 * Process the SCSI task when no LUN is attached. 537 * 538 * \param task SCSI task. 539 */ 540 void spdk_scsi_task_process_null_lun(struct spdk_scsi_task *task); 541 542 /** 543 * Process the aborted SCSI task. 544 * 545 * \param task SCSI task. 546 */ 547 void spdk_scsi_task_process_abort(struct spdk_scsi_task *task); 548 549 /** 550 * Open a logical unit for I/O operations. 551 * 552 * The registered callback function must get all tasks from the upper layer 553 * (e.g. iSCSI) to the LUN done, free the IO channel of the LUN if allocated, 554 * and then close the LUN. 555 * 556 * \param lun Logical unit to open. 557 * \param hotremove_cb Callback function for hot removal of the logical unit. 558 * \param hotremove_ctx Param for hot removal callback function. 559 * \param desc Output parameter for the descriptor when operation is successful. 560 * \return 0 if operation is successful, suitable errno value otherwise 561 */ 562 int spdk_scsi_lun_open(struct spdk_scsi_lun *lun, spdk_scsi_lun_remove_cb_t hotremove_cb, 563 void *hotremove_ctx, struct spdk_scsi_lun_desc **desc); 564 565 /** 566 * Close an opened logical unit. 567 * 568 * \param desc Descriptor of the logical unit. 569 */ 570 void spdk_scsi_lun_close(struct spdk_scsi_lun_desc *desc); 571 572 /** 573 * Allocate I/O channel for the LUN 574 * 575 * \param desc Descriptor of the logical unit. 576 * 577 * \return 0 on success, -1 on failure. 578 */ 579 int spdk_scsi_lun_allocate_io_channel(struct spdk_scsi_lun_desc *desc); 580 581 /** 582 * Free I/O channel from the logical unit 583 * 584 * \param desc Descriptor of the logical unit. 585 */ 586 void spdk_scsi_lun_free_io_channel(struct spdk_scsi_lun_desc *desc); 587 588 /** 589 * Get DIF context for SCSI LUN and SCSI command. 590 * 591 * \param lun Logical unit. 592 * \param task SCSI task which has the payload. 593 * \param dif_ctx Output parameter which will contain initialized DIF context. 594 * 595 * \return true on success or false otherwise. 596 */ 597 bool spdk_scsi_lun_get_dif_ctx(struct spdk_scsi_lun *lun, struct spdk_scsi_task *task, 598 struct spdk_dif_ctx *dif_ctx); 599 600 /** 601 * Set iSCSI Initiator port TransportID 602 * 603 * \param port SCSI initiator port. 604 * \param iscsi_name Initiator name. 605 * \param isid Session ID. 606 */ 607 void spdk_scsi_port_set_iscsi_transport_id(struct spdk_scsi_port *port, 608 char *iscsi_name, uint64_t isid); 609 610 /** 611 * Convert LUN ID from integer to LUN format 612 * 613 * \param lun_id Integer LUN ID 614 * 615 * \return LUN format of LUN ID 616 */ 617 uint64_t spdk_scsi_lun_id_int_to_fmt(int lun_id); 618 619 /** 620 * Convert LUN ID from LUN format to integer 621 * 622 * \param fmt_lun LUN format of LUN ID 623 * 624 * \return integer LUN ID 625 */ 626 int spdk_scsi_lun_id_fmt_to_int(uint64_t fmt_lun); 627 #ifdef __cplusplus 628 } 629 #endif 630 631 #endif /* SPDK_SCSI_H */ 632