Commit 3fe67632 authored by Yanbo Zhou's avatar Yanbo Zhou Committed by Jim Harris
Browse files

include/scsi.h: add comments for public APIs 



Change-Id: Id315ae334062ee46d89c236cc5da7b42ec92eaac
Signed-off-by: default avatarYanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/411213


Reviewed-by: default avatarShuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Reviewed-by: default avatarBen Walker <benjamin.walker@intel.com>
Tested-by: default avatarSPDK Automated Test System <sys_sgsw@intel.com>
parent bad7601c

include/spdk/scsi.h

+245 −13
Original line number Diff line number Diff line
@@ -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].

 * 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);

const char *spdk_scsi_port_get_name(const struct spdk_scsi_port *port);



/**

 * 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