include/scsi.h: add comments for public APIs
Change-Id: Id315ae334062ee46d89c236cc5da7b42ec92eaac Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com> Reviewed-on: https://review.gerrithub.io/411213 Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
This commit is contained in:
Yanbo Zhou
Jim Harris
parent
bad7601c8e
commit
3fe6763242
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user