scsi.h File Reference

SCSI to bdev translation layer. More...

Data Structures

struct  spdk_scsi_task
 

Macros

#define OWNER_SCSI_DEV   0x10
 
#define OBJECT_SCSI_TASK   0x10
 
#define TRACE_GROUP_SCSI   0x2
 
#define TRACE_SCSI_TASK_DONE   SPDK_TPOINT_ID(TRACE_GROUP_SCSI, 0x0)
 
#define TRACE_SCSI_TASK_START   SPDK_TPOINT_ID(TRACE_GROUP_SCSI, 0x1)
 
#define SPDK_SCSI_MAX_DEVS   1024
 
#define SPDK_SCSI_DEV_MAX_LUN   64
 
#define SPDK_SCSI_DEV_MAX_PORTS   4
 
#define SPDK_SCSI_DEV_MAX_NAME   255
 
#define SPDK_SCSI_PORT_MAX_NAME_LENGTH   255
 
#define SPDK_SCSI_MAX_TRANSPORT_ID_LENGTH   255
 

Typedefs

typedef void(* spdk_scsi_task_cpl) (struct spdk_scsi_task *task)
 
typedef void(* spdk_scsi_task_free) (struct spdk_scsi_task *task)
 
typedef void(* spdk_scsi_lun_remove_cb_t) (struct spdk_scsi_lun *, void *)
 
typedef void(* spdk_scsi_dev_destruct_cb_t) (void *cb_arg, int rc)
 

Enumerations

enum  spdk_scsi_data_dir { SPDK_SCSI_DIR_NONE = 0, SPDK_SCSI_DIR_TO_DEV = 1, SPDK_SCSI_DIR_FROM_DEV = 2 }
 
enum  spdk_scsi_task_func { SPDK_SCSI_TASK_FUNC_ABORT_TASK = 0, SPDK_SCSI_TASK_FUNC_ABORT_TASK_SET, SPDK_SCSI_TASK_FUNC_CLEAR_TASK_SET, SPDK_SCSI_TASK_FUNC_LUN_RESET }
 
enum  spdk_scsi_task_mgmt_resp {
  SPDK_SCSI_TASK_MGMT_RESP_COMPLETE, SPDK_SCSI_TASK_MGMT_RESP_SUCCESS, SPDK_SCSI_TASK_MGMT_RESP_REJECT, SPDK_SCSI_TASK_MGMT_RESP_INVALID_LUN,
  SPDK_SCSI_TASK_MGMT_RESP_TARGET_FAILURE, SPDK_SCSI_TASK_MGMT_RESP_REJECT_FUNC_NOT_SUPPORTED
}
 

Functions

int spdk_scsi_init (void)
 Initialize SCSI layer. More...
 
void spdk_scsi_fini (void)
 Stop and clean the SCSI layer.
 
int spdk_scsi_lun_get_id (const struct spdk_scsi_lun *lun)
 Get the LUN id of the given logical unit. More...
 
const char * spdk_scsi_lun_get_bdev_name (const struct spdk_scsi_lun *lun)
 Get the name of the bdev associated with the given logical unit. More...
 
const struct spdk_scsi_dev * spdk_scsi_lun_get_dev (const struct spdk_scsi_lun *lun)
 Get the SCSI device associated with the given logical unit. More...
 
bool spdk_scsi_lun_is_removing (const struct spdk_scsi_lun *lun)
 Check if the logical unit is hot removing. More...
 
const char * spdk_scsi_dev_get_name (const struct spdk_scsi_dev *dev)
 Get the name of the given SCSI device. More...
 
int spdk_scsi_dev_get_id (const struct spdk_scsi_dev *dev)
 Get the id of the given SCSI device. More...
 
struct spdk_scsi_lun * spdk_scsi_dev_get_lun (struct spdk_scsi_dev *dev, int lun_id)
 Get the logical unit of the given SCSI device whose id is lun_id. More...
 
bool spdk_scsi_dev_has_pending_tasks (const struct spdk_scsi_dev *dev, const struct spdk_scsi_port *initiator_port)
 Check whether the SCSI device has any pending task. More...
 
void spdk_scsi_dev_destruct (struct spdk_scsi_dev *dev, spdk_scsi_dev_destruct_cb_t cb_fn, void *cb_arg)
 Destruct the SCSI decice. More...
 
void spdk_scsi_dev_queue_mgmt_task (struct spdk_scsi_dev *dev, struct spdk_scsi_task *task)
 Execute the SCSI management task. More...
 
void spdk_scsi_dev_queue_task (struct spdk_scsi_dev *dev, struct spdk_scsi_task *task)
 Execute the SCSI task. More...
 
int spdk_scsi_dev_add_port (struct spdk_scsi_dev *dev, uint64_t id, const char *name)
 Add a new port to the given SCSI device. More...
 
int spdk_scsi_dev_delete_port (struct spdk_scsi_dev *dev, uint64_t id)
 Delete a specified port of the given SCSI device. More...
 
struct spdk_scsi_port * spdk_scsi_dev_find_port_by_id (struct spdk_scsi_dev *dev, uint64_t id)
 Get the port of the given SCSI device whose port ID is id. More...
 
int spdk_scsi_dev_allocate_io_channels (struct spdk_scsi_dev *dev)
 Allocate I/O channels for all LUNs of the given SCSI device. More...
 
void spdk_scsi_dev_free_io_channels (struct spdk_scsi_dev *dev)
 Free I/O channels from all LUNs of the given SCSI device.
 
struct spdk_scsi_dev * spdk_scsi_dev_construct (const char *name, const char *bdev_name_list[], int *lun_id_list, int num_luns, uint8_t protocol_id, void(*hotremove_cb)(const struct spdk_scsi_lun *, void *), void *hotremove_ctx)
 Construct a SCSI device object using the given parameters. More...
 
void spdk_scsi_dev_delete_lun (struct spdk_scsi_dev *dev, struct spdk_scsi_lun *lun)
 Delete a logical unit of the given SCSI device. More...
 
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)
 Add a new logical unit to the given SCSI device. More...
 
struct spdk_scsi_port * spdk_scsi_port_create (uint64_t id, uint16_t index, const char *name)
 Create a new SCSI port. More...
 
void spdk_scsi_port_free (struct spdk_scsi_port **pport)
 Free the SCSI port. More...
 
const char * spdk_scsi_port_get_name (const struct spdk_scsi_port *port)
 Get the name of the SCSI port. More...
 
void spdk_scsi_task_construct (struct spdk_scsi_task *task, spdk_scsi_task_cpl cpl_fn, spdk_scsi_task_free free_fn)
 Construct a new SCSI task. More...
 
void spdk_scsi_task_put (struct spdk_scsi_task *task)
 Put the SCSI task. More...
 
void spdk_scsi_task_set_data (struct spdk_scsi_task *task, void *data, uint32_t len)
 Set internal buffer to given one. More...
 
int spdk_scsi_task_scatter_data (struct spdk_scsi_task *task, const void *src, size_t len)
 Single buffer -> vector of buffers. More...
 
void * spdk_scsi_task_gather_data (struct spdk_scsi_task *task, int *len)
 Vector of buffers -> single buffer. More...
 
void spdk_scsi_task_build_sense_data (struct spdk_scsi_task *task, int sk, int asc, int ascq)
 Build sense data for the SCSI task. More...
 
void spdk_scsi_task_set_status (struct spdk_scsi_task *task, int sc, int sk, int asc, int ascq)
 Set SCSI status code to the SCSI task. More...
 
void spdk_scsi_task_copy_status (struct spdk_scsi_task *dst, struct spdk_scsi_task *src)
 Copy SCSI status. More...
 
void spdk_scsi_task_process_null_lun (struct spdk_scsi_task *task)
 Process the SCSI task when no LUN is attached. More...
 
void spdk_scsi_task_process_abort (struct spdk_scsi_task *task)
 Process the aborted SCSI task. More...
 
int spdk_scsi_lun_open (struct spdk_scsi_lun *lun, spdk_scsi_lun_remove_cb_t hotremove_cb, void *hotremove_ctx, struct spdk_scsi_lun_desc **desc)
 Open a logical unit for I/O operations. More...
 
void spdk_scsi_lun_close (struct spdk_scsi_lun_desc *desc)
 Close an opened logical unit. More...
 
int spdk_scsi_lun_allocate_io_channel (struct spdk_scsi_lun_desc *desc)
 Allocate I/O channel for the LUN. More...
 
void spdk_scsi_lun_free_io_channel (struct spdk_scsi_lun_desc *desc)
 Free I/O channel from the logical unit. More...
 
bool spdk_scsi_lun_get_dif_ctx (struct spdk_scsi_lun *lun, struct spdk_scsi_task *task, struct spdk_dif_ctx *dif_ctx)
 Get DIF context for SCSI LUN and SCSI command. More...
 
void spdk_scsi_port_set_iscsi_transport_id (struct spdk_scsi_port *port, char *iscsi_name, uint64_t isid)
 Set iSCSI Initiator port TransportID. More...
 
uint64_t spdk_scsi_lun_id_int_to_fmt (int lun_id)
 Convert LUN ID from integer to LUN format. More...
 
int spdk_scsi_lun_id_fmt_to_int (uint64_t fmt_lun)
 Convert LUN ID from LUN format to integer. More...
 

Detailed Description

SCSI to bdev translation layer.

Function Documentation

◆ spdk_scsi_dev_add_lun()

int spdk_scsi_dev_add_lun ( struct spdk_scsi_dev *  dev,
const char *  bdev_name,
int  lun_id,
void(*)(const struct spdk_scsi_lun *, void *)  hotremove_cb,
void *  hotremove_ctx 
)

Add a new logical unit to the given SCSI device.

Parameters
devSCSI device.
bdev_nameName of the bdev attached to the logical unit.
lun_idLUN id for the new logical unit.
hotremove_cbCallback to lun hotremoval. Will be called once hotremove is first triggered.
hotremove_ctxAdditional argument to hotremove_cb.

◆ spdk_scsi_dev_add_port()

int spdk_scsi_dev_add_port ( struct spdk_scsi_dev *  dev,
uint64_t  id,
const char *  name 
)

Add a new port to the given SCSI device.

Parameters
devSCSI device.
idPort id.
namePort name.
Returns
0 on success, -1 on failure.

◆ spdk_scsi_dev_allocate_io_channels()

int spdk_scsi_dev_allocate_io_channels ( struct spdk_scsi_dev *  dev)

Allocate I/O channels for all LUNs of the given SCSI device.

Parameters
devSCSI device.
Returns
0 on success, -1 on failure.

◆ spdk_scsi_dev_construct()

struct spdk_scsi_dev* spdk_scsi_dev_construct ( const char *  name,
const char *  bdev_name_list[],
int *  lun_id_list,
int  num_luns,
uint8_t  protocol_id,
void(*)(const struct spdk_scsi_lun *, void *)  hotremove_cb,
void *  hotremove_ctx 
)

Construct a SCSI device object using the given parameters.

Parameters
nameName for the SCSI device.
bdev_name_listList of bdev names to attach to the LUNs for this SCSI device.
lun_id_listList 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].
num_lunsNumber of entries in lun_list and lun_id_list.
protocol_idSCSI SPC protocol identifier to report in INQUIRY data
hotremove_cbCallback to lun hotremoval. Will be called once hotremove is first triggered.
hotremove_ctxAdditional argument to hotremove_cb.
Returns
the constructed spdk_scsi_dev object.

◆ spdk_scsi_dev_delete_lun()

void spdk_scsi_dev_delete_lun ( struct spdk_scsi_dev *  dev,
struct spdk_scsi_lun *  lun 
)

Delete a logical unit of the given SCSI device.

Parameters
devSCSI device.
lunLogical unit to delete.

◆ spdk_scsi_dev_delete_port()

int spdk_scsi_dev_delete_port ( struct spdk_scsi_dev *  dev,
uint64_t  id 
)

Delete a specified port of the given SCSI device.

Parameters
devSCSI device.
idPort id.
Returns
0 on success, -1 on failure.

◆ spdk_scsi_dev_destruct()

void spdk_scsi_dev_destruct ( struct spdk_scsi_dev *  dev,
spdk_scsi_dev_destruct_cb_t  cb_fn,
void *  cb_arg 
)

Destruct the SCSI decice.

Parameters
devSCSI device.
cb_fnCallback function.
cb_argArgument to callback function.

◆ spdk_scsi_dev_find_port_by_id()

struct spdk_scsi_port* spdk_scsi_dev_find_port_by_id ( struct spdk_scsi_dev *  dev,
uint64_t  id 
)

Get the port of the given SCSI device whose port ID is id.

Parameters
devSCSI device.
idPort id.
Returns
the port of the SCSI device on success, or NULL on failure.

◆ spdk_scsi_dev_get_id()

int spdk_scsi_dev_get_id ( const struct spdk_scsi_dev *  dev)

Get the id of the given SCSI device.

Parameters
devSCSI device.
Returns
the id of the SCSI device.

◆ spdk_scsi_dev_get_lun()

struct spdk_scsi_lun* spdk_scsi_dev_get_lun ( struct spdk_scsi_dev *  dev,
int  lun_id 
)

Get the logical unit of the given SCSI device whose id is lun_id.

Parameters
devSCSI device.
lun_idId of the logical unit.
Returns
the logical unit on success, or NULL on failure.

◆ spdk_scsi_dev_get_name()

const char* spdk_scsi_dev_get_name ( const struct spdk_scsi_dev *  dev)

Get the name of the given SCSI device.

Parameters
devSCSI device.
Returns
the name of the SCSI device on success, or NULL on failure.

◆ spdk_scsi_dev_has_pending_tasks()

bool spdk_scsi_dev_has_pending_tasks ( const struct spdk_scsi_dev *  dev,
const struct spdk_scsi_port *  initiator_port 
)

Check whether the SCSI device has any pending task.

Parameters
devSCSI device.
initiator_portCheck tasks only from the initiator if specified, or all all tasks otherwise.
Returns
true if the SCSI device has any pending task, or false otherwise.

◆ spdk_scsi_dev_queue_mgmt_task()

void spdk_scsi_dev_queue_mgmt_task ( struct spdk_scsi_dev *  dev,
struct spdk_scsi_task task 
)

Execute the SCSI management task.

The task can be constructed by the function spdk_scsi_task_construct(). Code of task management function to be executed is set before calling this API.

Parameters
devSCSI device.
taskSCSI task to be executed.

◆ spdk_scsi_dev_queue_task()

void spdk_scsi_dev_queue_task ( struct spdk_scsi_dev *  dev,
struct spdk_scsi_task task 
)

Execute the SCSI task.

The task can be constructed by the function spdk_scsi_task_construct().

Parameters
devSCSI device.
taskTask to be executed.

◆ spdk_scsi_init()

int spdk_scsi_init ( void  )

Initialize SCSI layer.

Returns
0 on success, -1 on failure.

◆ spdk_scsi_lun_allocate_io_channel()

int spdk_scsi_lun_allocate_io_channel ( struct spdk_scsi_lun_desc *  desc)

Allocate I/O channel for the LUN.

Parameters
descDescriptor of the logical unit.
Returns
0 on success, -1 on failure.

◆ spdk_scsi_lun_close()

void spdk_scsi_lun_close ( struct spdk_scsi_lun_desc *  desc)

Close an opened logical unit.

Parameters
descDescriptor of the logical unit.

◆ spdk_scsi_lun_free_io_channel()

void spdk_scsi_lun_free_io_channel ( struct spdk_scsi_lun_desc *  desc)

Free I/O channel from the logical unit.

Parameters
descDescriptor of the logical unit.

◆ spdk_scsi_lun_get_bdev_name()

const char* spdk_scsi_lun_get_bdev_name ( const struct spdk_scsi_lun *  lun)

Get the name of the bdev associated with the given logical unit.

Parameters
lunLogical unit.
Returns
the name of the bdev associated with the logical unit.

◆ spdk_scsi_lun_get_dev()

const struct spdk_scsi_dev* spdk_scsi_lun_get_dev ( const struct spdk_scsi_lun *  lun)

Get the SCSI device associated with the given logical unit.

Parameters
lunLogical unit.
Returns
the SCSI device associated with the logical unit.

◆ spdk_scsi_lun_get_dif_ctx()

bool spdk_scsi_lun_get_dif_ctx ( struct spdk_scsi_lun *  lun,
struct spdk_scsi_task task,
struct spdk_dif_ctx dif_ctx 
)

Get DIF context for SCSI LUN and SCSI command.

Parameters
lunLogical unit.
taskSCSI task which has the payload.
dif_ctxOutput parameter which will contain initialized DIF context.
Returns
true on success or false otherwise.

◆ spdk_scsi_lun_get_id()

int spdk_scsi_lun_get_id ( const struct spdk_scsi_lun *  lun)

Get the LUN id of the given logical unit.

Parameters
lunLogical unit.
Returns
LUN id of the logical unit.

◆ spdk_scsi_lun_id_fmt_to_int()

int spdk_scsi_lun_id_fmt_to_int ( uint64_t  fmt_lun)

Convert LUN ID from LUN format to integer.

Parameters
fmt_lunLUN format of LUN ID
Returns
integer LUN ID

◆ spdk_scsi_lun_id_int_to_fmt()

uint64_t spdk_scsi_lun_id_int_to_fmt ( int  lun_id)

Convert LUN ID from integer to LUN format.

Parameters
lun_idInteger LUN ID
Returns
LUN format of LUN ID

◆ spdk_scsi_lun_is_removing()

bool spdk_scsi_lun_is_removing ( const struct spdk_scsi_lun *  lun)

Check if the logical unit is hot removing.

Parameters
lunLogical unit
Returns
true if removing, false otherwise.

◆ spdk_scsi_lun_open()

int spdk_scsi_lun_open ( struct spdk_scsi_lun *  lun,
spdk_scsi_lun_remove_cb_t  hotremove_cb,
void *  hotremove_ctx,
struct spdk_scsi_lun_desc **  desc 
)

Open a logical unit for I/O operations.

The registered callback function must get all tasks from the upper layer (e.g. iSCSI) to the LUN done, free the IO channel of the LUN if allocated, and then close the LUN.

Parameters
lunLogical unit to open.
hotremove_cbCallback function for hot removal of the logical unit.
hotremove_ctxParam for hot removal callback function.
descOutput parameter for the descriptor when operation is successful.
Returns
0 if operation is successful, suitable errno value otherwise

◆ spdk_scsi_port_create()

struct spdk_scsi_port* spdk_scsi_port_create ( uint64_t  id,
uint16_t  index,
const char *  name 
)

Create a new SCSI port.

Parameters
idPort id.
indexPort index.
namePort Name.
Returns
a pointer to the created SCSI port on success, or NULL on failure.

◆ spdk_scsi_port_free()

void spdk_scsi_port_free ( struct spdk_scsi_port **  pport)

Free the SCSI port.

Parameters
pportSCSI port to free.

◆ spdk_scsi_port_get_name()

const char* spdk_scsi_port_get_name ( const struct spdk_scsi_port *  port)

Get the name of the SCSI port.

Parameters
portSCSI port to query.
Returns
the name of the SCSI port.

◆ spdk_scsi_port_set_iscsi_transport_id()

void spdk_scsi_port_set_iscsi_transport_id ( struct spdk_scsi_port *  port,
char *  iscsi_name,
uint64_t  isid 
)

Set iSCSI Initiator port TransportID.

Parameters
portSCSI initiator port.
iscsi_nameInitiator name.
isidSession ID.

◆ spdk_scsi_task_build_sense_data()

void spdk_scsi_task_build_sense_data ( struct spdk_scsi_task task,
int  sk,
int  asc,
int  ascq 
)

Build sense data for the SCSI task.

Parameters
taskSCSI task.
skSense key.
ascAdditional sense code.
ascqAdditional sense code qualifier.

◆ spdk_scsi_task_construct()

void spdk_scsi_task_construct ( struct spdk_scsi_task task,
spdk_scsi_task_cpl  cpl_fn,
spdk_scsi_task_free  free_fn 
)

Construct a new SCSI task.

Parameters
taskSCSI task to consturct.
cpl_fnCalled when the task is completed.
free_fnCalled when the task is freed

◆ spdk_scsi_task_copy_status()

void spdk_scsi_task_copy_status ( struct spdk_scsi_task dst,
struct spdk_scsi_task src 
)

Copy SCSI status.

Parameters
dstSCSI task whose status is written to.
srcSCSI task whose status is read from.

◆ spdk_scsi_task_gather_data()

void* spdk_scsi_task_gather_data ( struct spdk_scsi_task task,
int *  len 
)

Vector of buffers -> single buffer.

Parameters
taskSCSI task,
lenLength of the buffer allocated and written into.
Returns
a pointer to the buffer allocated and written into.

◆ spdk_scsi_task_process_abort()

void spdk_scsi_task_process_abort ( struct spdk_scsi_task task)

Process the aborted SCSI task.

Parameters
taskSCSI task.

◆ spdk_scsi_task_process_null_lun()

void spdk_scsi_task_process_null_lun ( struct spdk_scsi_task task)

Process the SCSI task when no LUN is attached.

Parameters
taskSCSI task.

◆ spdk_scsi_task_put()

void spdk_scsi_task_put ( struct spdk_scsi_task task)

Put the SCSI task.

Parameters
taskSCSI task to put.

◆ spdk_scsi_task_scatter_data()

int spdk_scsi_task_scatter_data ( struct spdk_scsi_task task,
const void *  src,
size_t  len 
)

Single buffer -> vector of buffers.

Parameters
taskSCSI task.
srcA pointer to the data buffer read from.
lenLength of the data buffer read from.
Returns
the total length of the vector of buffers written into on success, or -1 on failure.

◆ spdk_scsi_task_set_data()

void spdk_scsi_task_set_data ( struct spdk_scsi_task task,
void *  data,
uint32_t  len 
)

Set internal buffer to given one.

Caller is owner of that buffer.

Parameters
taskSCSI task.
dataPointer to buffer.
lenBuffer length.

◆ spdk_scsi_task_set_status()

void spdk_scsi_task_set_status ( struct spdk_scsi_task task,
int  sc,
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.

Parameters
taskSCSI task.
scSense code
skSense key.
ascAdditional sense code.
ascqAdditional sense code qualifier.