diff --git a/include/spdk/scsi.h b/include/spdk/scsi.h index 530200cda..caa91fff2 100644 --- a/include/spdk/scsi.h +++ b/include/spdk/scsi.h @@ -146,42 +146,170 @@ struct spdk_scsi_port; struct spdk_scsi_dev; struct spdk_scsi_lun; +/** + * Initialize SCSI layer. + * + * \return 0 on success, -1 on failure. + */ int spdk_scsi_init(void); +/** + * Stop and clean the SCSI layer. + */ void spdk_scsi_fini(void); +/** + * Get the LUN id of the given logical unit. + * + * \param lun Logical unit. + * + * \return LUN id of the logical unit. + */ int spdk_scsi_lun_get_id(const struct spdk_scsi_lun *lun); + +/** + * Get the name of the bdev associated with the given logical unit. + * + * \param lun Logical unit. + * + * \return the name of the bdev associated with the logical unit. + */ const char *spdk_scsi_lun_get_bdev_name(const struct spdk_scsi_lun *lun); + +/** + * Get the SCSI device associated with the given logical unit. + * + * \param lun Logical unit. + * + * \return the SCSI device associated with the logical unit. + */ const struct spdk_scsi_dev *spdk_scsi_lun_get_dev(const struct spdk_scsi_lun *lun); +/** + * Get the name of the given SCSI device. + * + * \param dev SCSI device. + * + * \return the name of the SCSI device on success, or NULL on failure. + */ const char *spdk_scsi_dev_get_name(const struct spdk_scsi_dev *dev); + +/** + * Get the id of the given SCSI device. + * + * \param dev SCSI device. + * + * \return the id of the SCSI device. + */ int spdk_scsi_dev_get_id(const struct spdk_scsi_dev *dev); + +/** + * Get the logical unit of the given SCSI device whose id is lun_id. + * + * \param dev SCSI device. + * \param id Id of the logical unit. + * + * \return the logical unit on success, or NULL on failure. + */ struct spdk_scsi_lun *spdk_scsi_dev_get_lun(struct spdk_scsi_dev *dev, int lun_id); + +/** + * Check whether the SCSI device has any pending task. + * + * \param dev SCSI device. + * + * \return true if the SCSI device has any pending task, or false otherwise. + */ bool spdk_scsi_dev_has_pending_tasks(const struct spdk_scsi_dev *dev); + +/** + * Destruct the SCSI decice. + * + * \param dev SCSI device. + */ void spdk_scsi_dev_destruct(struct spdk_scsi_dev *dev); + +/** + * Execute the SCSI management task. + * + * The task can be constructed by the function spdk_scsi_task_construct(). + * + * \param dev SCSI device. + * \param task SCSI task to be executed. + * \param func Task management function to be executed. + */ void spdk_scsi_dev_queue_mgmt_task(struct spdk_scsi_dev *dev, struct spdk_scsi_task *task, enum spdk_scsi_task_func func); +/** + * Execute the SCSI task. + * + * The task can be constructed by the function spdk_scsi_task_construct(). + * + * \param dev SCSI device. + * \param task Task to be executed. + */ void spdk_scsi_dev_queue_task(struct spdk_scsi_dev *dev, struct spdk_scsi_task *task); + +/** + * Add a new port to the given SCSI device. + * + * \param dev SCSI device. + * \param id Port id. + * \param name Port name. + * + * \return 0 on success, -1 on failure. + */ int spdk_scsi_dev_add_port(struct spdk_scsi_dev *dev, uint64_t id, const char *name); + +/** + * Delete a specified port of the given SCSI device. + * + * \param dev SCSI device. + * \param id Port id. + * + * \return 0 on success, -1 on failure. + */ int spdk_scsi_dev_delete_port(struct spdk_scsi_dev *dev, uint64_t id); + +/** + * Get the port of the given SCSI device whose port ID is id. + * + * \param dev SCSI device. + * \param id Port id. + * + * \return the port of the SCSI device on success, or NULL on failure. + */ struct spdk_scsi_port *spdk_scsi_dev_find_port_by_id(struct spdk_scsi_dev *dev, uint64_t id); + +/** + * Allocate I/O channels for all LUNs of the given SCSI device. + * + * \param dev SCSI device. + * + * \return 0 on success, -1 on failure. + */ int spdk_scsi_dev_allocate_io_channels(struct spdk_scsi_dev *dev); + +/** + * Free I/O channels from all LUNs of the given SCSI device. + */ void spdk_scsi_dev_free_io_channels(struct spdk_scsi_dev *dev); /** - * \brief Constructs a SCSI device object using the given parameters. + * Construct a SCSI device object using the given parameters. * * \param name Name for the SCSI device. * \param bdev_name_list List of bdev names to attach to the LUNs for this SCSI - * device. - * \param lun_id_list List of LUN IDs for the LUN in this SCSI device. Caller is - * responsible for managing the memory containing this list. - * lun_id_list[x] is the LUN ID for lun_list[x]. + * device. + * \param lun_id_list List of LUN IDs for the LUN in this SCSI device. Caller is + * responsible for managing the memory containing this list. lun_id_list[x] is + * the LUN ID for lun_list[x]. * \param num_luns Number of entries in lun_list and lun_id_list. - * \param hotremove_cb Callback to lun hotremoval. Will be called - * once hotremove is first triggered. - * \param hotremove_ctx Additional argument to hotremove_cb - * \return The constructed spdk_scsi_dev object. + * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove + * is first triggered. + * \param hotremove_ctx Additional argument to hotremove_cb. + * + * \return the constructed spdk_scsi_dev object. */ struct spdk_scsi_dev *spdk_scsi_dev_construct(const char *name, const char *bdev_name_list[], @@ -191,37 +319,141 @@ struct spdk_scsi_dev *spdk_scsi_dev_construct(const char *name, void (*hotremove_cb)(const struct spdk_scsi_lun *, void *), void *hotremove_ctx); +/** + * Delete a logical unit of the given SCSI device. + * + * \param dev SCSI device. + * \param lun Logical unit to delete. + */ void spdk_scsi_dev_delete_lun(struct spdk_scsi_dev *dev, struct spdk_scsi_lun *lun); + +/** + * Add a new logical unit to the given SCSI device. + * + * \param dev SCSI device. + * \param bdev_name Name of the bdev attached to the logical unit. + * \param lun_id LUN id for the new logical unit. + * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove + * is first triggered. + * \param hotremove_ctx Additional argument to hotremove_cb. + */ int spdk_scsi_dev_add_lun(struct spdk_scsi_dev *dev, const char *bdev_name, int lun_id, void (*hotremove_cb)(const struct spdk_scsi_lun *, void *), void *hotremove_ctx); +/** + * Create a new SCSI port. + * + * \param id Port id. + * \param index Port index. + * \param name Port Name. + * + * \return a pointer to the created SCSI port on success, or NULL on failure. + */ struct spdk_scsi_port *spdk_scsi_port_create(uint64_t id, uint16_t index, const char *name); + +/** + * Free the SCSI port. + * + * \param pport SCSI port to free. + */ void spdk_scsi_port_free(struct spdk_scsi_port **pport); + +/** + * Get the name of the SCSI port. + * + * \param SCSI port to query. + * + * \return the name of the SCSI port. + */ const char *spdk_scsi_port_get_name(const struct spdk_scsi_port *port); - +/** + * Construct a new SCSI task. + * + * \param task SCSI task to consturct. + * \param cpl_fn Called when the task is completed. + * \param free_fn Called when the task is freed + */ void spdk_scsi_task_construct(struct spdk_scsi_task *task, spdk_scsi_task_cpl cpl_fn, spdk_scsi_task_free free_fn); + +/** + * Put the SCSI task. + * + * \param task SCSI task to put. + */ void spdk_scsi_task_put(struct spdk_scsi_task *task); /** * Set internal buffer to given one. Caller is owner of that buffer. * - * \param task Task struct - * \param data Pointer to buffer - * \param len Buffer length + * \param task SCSI task. + * \param data Pointer to buffer. + * \param len Buffer length. */ void spdk_scsi_task_set_data(struct spdk_scsi_task *task, void *data, uint32_t len); +/** + * Single buffer -> vector of buffers. + * + * \param task SCSI task. + * \param src A pointer to the data buffer read from. + * \param len Length of the data buffer read from. + * + * \return the total length of the vector of buffers written into on success, or + * -1 on failure. + */ int spdk_scsi_task_scatter_data(struct spdk_scsi_task *task, const void *src, size_t len); + +/** + * Vector of buffers -> single buffer. + * + * \param task SCSI task, + * \param len Length of the buffer allocated and written into. + * + * \return a pointer to the buffer allocated and written into. + */ void *spdk_scsi_task_gather_data(struct spdk_scsi_task *task, int *len); + +/** + * Build sense data for the SCSI task. + * + * \param task SCSI task. + * \param sk Sense key. + * \param asc Additional sense code. + * \param ascq Additional sense code qualifier. + */ void spdk_scsi_task_build_sense_data(struct spdk_scsi_task *task, int sk, int asc, int ascq); + +/** + * Set SCSI status code to the SCSI task. When the status code is CHECK CONDITION, + * sense data is build too. + * + * \param task SCSI task. + * \param sc Sense code + * \param sk Sense key. + * \param asc Additional sense code. + * \param ascq Additional sense code qualifier. + */ void spdk_scsi_task_set_status(struct spdk_scsi_task *task, int sc, int sk, int asc, int ascq); + +/** + * Copy SCSI status. + * + * \param dst SCSI task whose status is written to. + * \param src SCSI task whose status is read from. + */ void spdk_scsi_task_copy_status(struct spdk_scsi_task *dst, struct spdk_scsi_task *src); + +/** + * Process the SCSI task when no LUN is attached. + * + * \param task SCSI task. + */ void spdk_scsi_task_process_null_lun(struct spdk_scsi_task *task); #ifdef __cplusplus