Introduction and Overview¶

TBD

Target core device interfaces¶

This section is blank because no kerneldoc comments have been added todrivers/target/target_core_device.c.

Target core transport interfaces¶

inttransport_init_session(struct se_session * se_sess)¶

initialize a session object

Parameters

structse_session*se_sess

Session object pointer.

Description

The caller must have zero-initializedse_sess before calling this function.

struct se_session *transport_alloc_session(enum target_prot_op sup_prot_ops)¶

allocate a session object and initialize it

Parameters

enumtarget_prot_opsup_prot_ops

bitmask that defines which T10-PI modes are supported.

inttransport_alloc_session_tags(struct se_session * se_sess, unsigned int tag_num, unsigned int tag_size)¶

allocate target driver private data

Parameters

structse_session*se_sess

Session pointer.

unsignedinttag_num

Maximum number of in-flight commands between initiator and target.

unsignedinttag_size

Size in bytes of the private data a target driver associates witheach command.

inttarget_submit_cmd_map_sgls(struct se_cmd * se_cmd, struct se_session * se_sess, unsigned char * cdb, unsigned char * sense, u64 unpacked_lun, u32 data_length, int task_attr, int data_dir, int flags, struct scatterlist * sgl, u32 sgl_count, struct scatterlist * sgl_bidi, u32 sgl_bidi_count, struct scatterlist * sgl_prot, u32 sgl_prot_count)¶

lookup unpacked lun and submit uninitialized se_cmd + use pre-allocated SGL memory.

Parameters

structse_cmd*se_cmd

command descriptor to submit

structse_session*se_sess

associated se_sess for endpoint

unsignedchar*cdb

pointer to SCSI CDB

unsignedchar*sense

pointer to SCSI sense buffer

u64unpacked_lun

unpacked LUN to reference for struct se_lun

u32data_length

fabric expected data transfer length

inttask_attr

SAM task attribute

intdata_dir

DMA data direction

intflags

flags for command submission from target_sc_flags_tables

structscatterlist*sgl

struct scatterlist memory for unidirectional mapping

u32sgl_count

scatterlist count for unidirectional mapping

structscatterlist*sgl_bidi

struct scatterlist memory for bidirectional READ mapping

u32sgl_bidi_count

scatterlist count for bidirectional READ mapping

structscatterlist*sgl_prot

struct scatterlist memory protection information

u32sgl_prot_count

scatterlist count for protection information

Description

Task tags are supported if the caller has setse_cmd->tag.

Returns non zero to signal active I/O shutdown failure. All othersetup exceptions will be returned as a SCSI CHECK_CONDITION response,but still return zero here.

This may only be called from process context, and also currentlyassumes internal allocation of fabric payload buffer by target-core.

inttarget_submit_cmd(struct se_cmd * se_cmd, struct se_session * se_sess, unsigned char * cdb, unsigned char * sense, u64 unpacked_lun, u32 data_length, int task_attr, int data_dir, int flags)¶

lookup unpacked lun and submit uninitialized se_cmd

Parameters

structse_cmd*se_cmd

command descriptor to submit

structse_session*se_sess

associated se_sess for endpoint

unsignedchar*cdb

pointer to SCSI CDB

unsignedchar*sense

pointer to SCSI sense buffer

u64unpacked_lun

unpacked LUN to reference for struct se_lun

u32data_length

fabric expected data transfer length

inttask_attr

SAM task attribute

intdata_dir

DMA data direction

intflags

flags for command submission from target_sc_flags_tables

Description

Task tags are supported if the caller has setse_cmd->tag.

Returns non zero to signal active I/O shutdown failure. All othersetup exceptions will be returned as a SCSI CHECK_CONDITION response,but still return zero here.

This may only be called from process context, and also currentlyassumes internal allocation of fabric payload buffer by target-core.

It also assumes interal target core SGL memory allocation.

inttarget_submit_tmr(struct se_cmd * se_cmd, struct se_session * se_sess, unsigned char * sense, u64 unpacked_lun, void * fabric_tmr_ptr, unsigned char tm_type, gfp_t gfp, u64 tag, int flags)¶

lookup unpacked lun and submit uninitialized se_cmd for TMR CDBs

Parameters

structse_cmd*se_cmd

command descriptor to submit

structse_session*se_sess

associated se_sess for endpoint

unsignedchar*sense

pointer to SCSI sense buffer

u64unpacked_lun

unpacked LUN to reference for struct se_lun

void*fabric_tmr_ptr

fabric context for TMR req

unsignedchartm_type

Type of TM request

gfp_tgfp

gfp type for caller

u64tag

referenced task tag for TMR_ABORT_TASK

intflags

submit cmd flags

Description

Callable from all contexts.

inttarget_get_sess_cmd(struct se_cmd * se_cmd, bool ack_kref)¶

Add command to active ->sess_cmd_list

Parameters

structse_cmd*se_cmd

command descriptor to add

boolack_kref

Signal that fabric will perform an acktarget_put_sess_cmd()

inttarget_put_sess_cmd(struct se_cmd * se_cmd)¶

decrease the command reference count

Parameters

structse_cmd*se_cmd

command to drop a reference from

Description

Returns 1 if and only if thistarget_put_sess_cmd() call caused therefcount to drop to zero. Returns zero otherwise.

voidtarget_sess_cmd_list_set_waiting(struct se_session * se_sess)¶

Set sess_tearing_down so no new commands are queued.

Parameters

structse_session*se_sess

session to flag

voidtarget_wait_for_sess_cmds(struct se_session * se_sess)¶

Wait for outstanding commands

Parameters

structse_session*se_sess

session to wait for active I/O

booltransport_wait_for_tasks(struct se_cmd * cmd)¶

set CMD_T_STOP and wait for t_transport_stop_comp

Parameters

structse_cmd*cmd

command to wait on

inttarget_send_busy(struct se_cmd * cmd)¶

Send SCSI BUSY status back to the initiator

Parameters

structse_cmd*cmd

SCSI command for which to send a BUSY reply.

Note

Only call this function if target_submit_cmd*() failed.

Target-supported userspace I/O¶

iSCSI helper functions¶

voidiscsi_prep_data_out_pdu(struct iscsi_task * task, struct iscsi_r2t_info * r2t, struct iscsi_data * hdr)¶

initialize Data-Out

Parameters

structiscsi_task*task

scsi command task

structiscsi_r2t_info*r2t

R2T info

structiscsi_data*hdr

iscsi data in pdu

Notes

Initialize Data-Out within this R2T sequence and findsproper data_offset within this SCSI command.

This function is called with connection lock taken.

voidiscsi_complete_scsi_task(struct iscsi_task * task, uint32_t exp_cmdsn, uint32_t max_cmdsn)¶

finish scsi task normally

Parameters

structiscsi_task*task

iscsi task for scsi cmd

uint32_texp_cmdsn

expected cmd sn in cpu format

uint32_tmax_cmdsn

max cmd sn in cpu format

Description

This is used when drivers do not need or cannot performlower level pdu processing.

Called with session back_lock

struct iscsi_task *iscsi_itt_to_task(struct iscsi_conn * conn, itt_t itt)¶

look up task by itt

Parameters

structiscsi_conn*conn

iscsi connection

itt_titt

itt

Description

This should be used for mgmt tasks like login and nops, or ifthe LDD’s itt space does not include the session age.

The session back_lock must be held.

int__iscsi_complete_pdu(struct iscsi_conn * conn, struct iscsi_hdr * hdr, char * data, int datalen)¶

complete pdu

Parameters

structiscsi_conn*conn

iscsi conn

structiscsi_hdr*hdr

iscsi header

char*data

data buffer

intdatalen

len of data buffer

Description

Completes pdu processing by freeing any resources allocated atqueuecommand or send generic. session back_lock must be held and verifyitt must have been called.

struct iscsi_task *iscsi_itt_to_ctask(struct iscsi_conn * conn, itt_t itt)¶

look up ctask by itt

Parameters

structiscsi_conn*conn

iscsi connection

itt_titt

itt

Description

This should be used for cmd tasks.

The session back_lock must be held.

voidiscsi_requeue_task(struct iscsi_task * task)¶

requeue task to run from session workqueue

Parameters

structiscsi_task*task

task to requeue

Description

LLDs that need to run a task from the session workqueue should callthis. The session frwd_lock must be held. This should only be calledby software drivers.

voidiscsi_suspend_queue(struct iscsi_conn * conn)¶

suspend iscsi_queuecommand

Parameters

structiscsi_conn*conn

iscsi conn to stop queueing IO on

Description

This grabs the session frwd_lock to make sure no one is inxmit_task/queuecommand, and then sets suspend to preventnew commands from being queued. This only needs to be calledby offload drivers that need to sync a path like ep disconnectwith the iscsi_queuecommand/xmit_task. To start IO again libiscsiwill call iscsi_start_tx and iscsi_unblock_session when in FFP.

voidiscsi_suspend_tx(struct iscsi_conn * conn)¶

suspend iscsi_data_xmit

Parameters

structiscsi_conn*conn

iscsi conn tp stop processing IO on.

Description

This function sets the suspend bit to prevent iscsi_data_xmitfrom sending new IO, and if work is queued on the xmit threadit will wait for it to be completed.

intiscsi_eh_session_reset(struct scsi_cmnd * sc)¶

drop session and attempt relogin

Parameters

structscsi_cmnd*sc

scsi command

Description

This function will wait for a relogin, session termination fromuserspace, or a recovery/replacement timeout.

intiscsi_eh_recover_target(struct scsi_cmnd * sc)¶

reset target and possibly the session

Parameters

structscsi_cmnd*sc

scsi command

Description

This will attempt to send a warm target reset. If that fails,we will escalate to ERL0 session recovery.

intiscsi_host_add(struct Scsi_Host * shost, structdevice * pdev)¶

add host to system

Parameters

structScsi_Host*shost

scsi host

structdevice*pdev

parent device

Description

This should be called by partial offload and software iscsi driversto add a host to the system.

struct Scsi_Host *iscsi_host_alloc(struct scsi_host_template * sht, int dd_data_size, bool xmit_can_sleep)¶

allocate a host and driver data

Parameters

structscsi_host_template*sht

scsi host template

intdd_data_size

driver host data size

boolxmit_can_sleep

bool indicating if LLD will queue IO from a work queue

Description

This should be called by partial offload and software iscsi drivers.To access the driver specific memory use the iscsi_host_priv() macro.

voidiscsi_host_remove(struct Scsi_Host * shost)¶

remove host and sessions

Parameters

structScsi_Host*shost

scsi host

Description

If there are any sessions left, this will initiate the removal and waitfor the completion.

struct iscsi_cls_session *iscsi_session_setup(struct iscsi_transport * iscsit, struct Scsi_Host * shost, uint16_t cmds_max, int dd_size, int cmd_task_size, uint32_t initial_cmdsn, unsigned int id)¶

create iscsi cls session and host and session

Parameters

structiscsi_transport*iscsit

iscsi transport template

structScsi_Host*shost

scsi host

uint16_tcmds_max

session can queue

intdd_size

private driver data size, added to session allocation size

intcmd_task_size

LLD task private data size

uint32_tinitial_cmdsn

initial CmdSN

unsignedintid

target ID to add to this session

Description

This can be used by software iscsi_transports that allocatea session per scsi host.

Callers should set cmds_max to the largest total numer (mgmt + scsi) oftasks they support. The iscsi layer reserves ISCSI_MGMT_CMDS_MAX tasksfor nop handling and login/logout requests.

voidiscsi_session_teardown(struct iscsi_cls_session * cls_session)¶

destroy session, host, and cls_session

Parameters

structiscsi_cls_session*cls_session

iscsi session

struct iscsi_cls_conn *iscsi_conn_setup(struct iscsi_cls_session * cls_session, int dd_size, uint32_t conn_idx)¶

create iscsi_cls_conn and iscsi_conn

Parameters

structiscsi_cls_session*cls_session

iscsi_cls_session

intdd_size

private driver data size

uint32_tconn_idx

cid

voidiscsi_conn_teardown(struct iscsi_cls_conn * cls_conn)¶

teardown iscsi connection

Parameters

structiscsi_cls_conn*cls_conn

iscsi class connection

Description

TODO: we may need to make this into a two step processlike scsi-mls remove + put host

iSCSI boot information¶

struct iscsi_boot_kobj *iscsi_boot_create_target(struct iscsi_boot_kset * boot_kset, int index, void * data, ssize_t (*show)(void *data, int type, char *buf), umode_t (*is_visible) (void *data, int type), void (*release) (void *data))¶

create boot target sysfs dir

Parameters

structiscsi_boot_kset*boot_kset

boot kset

intindex

the target id

void*data

driver specific data for target

ssize_t(*)(void*data,inttype,char*buf)show

attr show function

umode_t(*)(void*data,inttype)is_visible

attr visibility function

void(*)(void*data)release

release function

Note

The boot sysfs lib will free the data passed in for the callerwhen all refs to the target kobject have been released.

struct iscsi_boot_kobj *iscsi_boot_create_initiator(struct iscsi_boot_kset * boot_kset, int index, void * data, ssize_t (*show)(void *data, int type, char *buf), umode_t (*is_visible) (void *data, int type), void (*release) (void *data))¶

create boot initiator sysfs dir

Parameters

structiscsi_boot_kset*boot_kset

boot kset

intindex

the initiator id

void*data

driver specific data

ssize_t(*)(void*data,inttype,char*buf)show

attr show function

umode_t(*)(void*data,inttype)is_visible

attr visibility function

void(*)(void*data)release

release function

Note

The boot sysfs lib will free the data passed in for the callerwhen all refs to the initiator kobject have been released.

struct iscsi_boot_kobj *iscsi_boot_create_ethernet(struct iscsi_boot_kset * boot_kset, int index, void * data, ssize_t (*show)(void *data, int type, char *buf), umode_t (*is_visible) (void *data, int type), void (*release) (void *data))¶

create boot ethernet sysfs dir

Parameters

structiscsi_boot_kset*boot_kset

boot kset

intindex

the ethernet device id

void*data

driver specific data

ssize_t(*)(void*data,inttype,char*buf)show

attr show function

umode_t(*)(void*data,inttype)is_visible

attr visibility function

void(*)(void*data)release

release function

Note

The boot sysfs lib will free the data passed in for the callerwhen all refs to the ethernet kobject have been released.

struct iscsi_boot_kobj *iscsi_boot_create_acpitbl(struct iscsi_boot_kset * boot_kset, int index, void * data, ssize_t (*show)(void *data, int type, char *buf), umode_t (*is_visible) (void *data, int type), void (*release) (void *data))¶

create boot acpi table sysfs dir

Parameters

structiscsi_boot_kset*boot_kset

boot kset

intindex

not used

void*data

driver specific data

ssize_t(*)(void*data,inttype,char*buf)show

attr show function

umode_t(*)(void*data,inttype)is_visible

attr visibility function

void(*)(void*data)release

release function

Note

The boot sysfs lib will free the data passed in for the callerwhen all refs to the acpitbl kobject have been released.

struct iscsi_boot_kset *iscsi_boot_create_kset(const char * set_name)¶

creates root sysfs tree

Parameters

constchar*set_name

name of root dir

struct iscsi_boot_kset *iscsi_boot_create_host_kset(unsigned int hostno)¶

creates root sysfs tree for a scsi host

Parameters

unsignedinthostno

host number of scsi host

voidiscsi_boot_destroy_kset(struct iscsi_boot_kset * boot_kset)¶

destroy kset and kobjects under it

Parameters

structiscsi_boot_kset*boot_kset

boot kset

Description

This will remove the kset and kobjects and attrs under it.

iSCSI transport class¶

The file drivers/scsi/scsi_transport_iscsi.c defines transportattributes for the iSCSI class, which sends SCSI packets over TCP/IPconnections.

struct iscsi_bus_flash_session *iscsi_create_flashnode_sess(struct Scsi_Host * shost, int index, struct iscsi_transport * transport, int dd_size)¶

Add flashnode session entry in sysfs

Parameters

structScsi_Host*shost

pointer to host data

intindex

index of flashnode to add in sysfs

structiscsi_transport*transport

pointer to transport data

intdd_size

total size to allocate

Description

Adds a sysfs entry for the flashnode session attributes

Return

pointer to allocated flashnode sess on successNULL on failure

struct iscsi_bus_flash_conn *iscsi_create_flashnode_conn(struct Scsi_Host * shost, struct iscsi_bus_flash_session * fnode_sess, struct iscsi_transport * transport, int dd_size)¶

Add flashnode conn entry in sysfs

Parameters

structScsi_Host*shost

pointer to host data

structiscsi_bus_flash_session*fnode_sess

pointer to the parent flashnode session entry

structiscsi_transport*transport

pointer to transport data

intdd_size

total size to allocate

Description

Adds a sysfs entry for the flashnode connection attributes

Return

pointer to allocated flashnode conn on successNULL on failure

structdevice *iscsi_find_flashnode_sess(struct Scsi_Host * shost, void * data, int (*fn)(structdevice *dev, void *data))¶

finds flashnode session entry

Parameters

structScsi_Host*shost

pointer to host data

void*data

pointer to data containing value to use for comparison

int(*)(structdevice*dev,void*data)fn

function pointer that does actual comparison

Description

Finds the flashnode session object comparing the data passed using logicdefined in passed function pointer

Return

pointer to found flashnode session device object on successNULL on failure

structdevice *iscsi_find_flashnode_conn(struct iscsi_bus_flash_session * fnode_sess)¶

finds flashnode connection entry

Parameters

structiscsi_bus_flash_session*fnode_sess

pointer to parent flashnode session entry

Description

Finds the flashnode connection object comparing the data passed using logicdefined in passed function pointer

Return

pointer to found flashnode connection device object on successNULL on failure

voidiscsi_destroy_flashnode_sess(struct iscsi_bus_flash_session * fnode_sess)¶

destroy flashnode session entry

Parameters

structiscsi_bus_flash_session*fnode_sess

pointer to flashnode session entry to be destroyed

Description

Deletes the flashnode session entry and all children flashnode connectionentries from sysfs

voidiscsi_destroy_all_flashnode(struct Scsi_Host * shost)¶

destroy all flashnode session entries

Parameters

structScsi_Host*shost

pointer to host data

Description

Destroys all the flashnode session entries and all corresponding childrenflashnode connection entries from sysfs

intiscsi_scan_finished(struct Scsi_Host * shost, unsigned long time)¶

helper to report when running scans are done

Parameters

structScsi_Host*shost

scsi host

unsignedlongtime

scan run time

Description

This function can be used by drives like qla4xxx to report to the scsilayer when the scans it kicked off at module load time are done.

intiscsi_block_scsi_eh(struct scsi_cmnd * cmd)¶

block scsi eh until session state has transistioned

Parameters

structscsi_cmnd*cmd

scsi cmd passed to scsi eh handler

Description

If the session is down this function will wait for the recoverytimer to fire or for the session to be logged back in. If therecovery timer fires then FAST_IO_FAIL is returned. The callershould pass this error value to the scsi eh.

voidiscsi_unblock_session(struct iscsi_cls_session * session)¶

set a session as logged in and start IO.

Parameters

structiscsi_cls_session*session

iscsi session

Description

Mark a session as ready to accept IO.

struct iscsi_cls_session *iscsi_create_session(struct Scsi_Host * shost, struct iscsi_transport * transport, int dd_size, unsigned int target_id)¶

create iscsi class session

Parameters

structScsi_Host*shost

scsi host

structiscsi_transport*transport

iscsi transport

intdd_size

private driver data size

unsignedinttarget_id

which target

Description

This can be called from a LLD or iscsi_transport.

struct iscsi_cls_conn *iscsi_create_conn(struct iscsi_cls_session * session, int dd_size, uint32_t cid)¶

create iscsi class connection

Parameters

structiscsi_cls_session*session

iscsi cls session

intdd_size

private driver data size

uint32_tcid

connection id

Description

This can be called from a LLD or iscsi_transport. The connectionis child of the session so cid must be unique for all connectionson the session.

Since we do not support MCS, cid will normally be zero. In some casesfor software iscsi we could be trying to preallocate a connection structin which case there could be two connection structs and cid would benon-zero.

intiscsi_destroy_conn(struct iscsi_cls_conn * conn)¶

destroy iscsi class connection

Parameters

structiscsi_cls_conn*conn

iscsi cls session

Description

This can be called from a LLD or iscsi_transport.

intiscsi_session_event(struct iscsi_cls_session * session, enum iscsi_uevent_e event)¶

send session destr. completion event

Parameters

structiscsi_cls_session*session

iscsi class session

enumiscsi_uevent_eevent

type of event

iSCSI TCP interfaces¶

intiscsi_sw_tcp_recv(read_descriptor_t * rd_desc, structsk_buff * skb, unsigned int offset, size_t len)¶

TCP receive in sendfile fashion

Parameters

read_descriptor_t*rd_desc

read descriptor

structsk_buff*skb

socket buffer

unsignedintoffset

offset in skb

size_tlen

skb->len - offset

intiscsi_sw_sk_state_check(structsock * sk)¶

check socket state

Parameters

structsock*sk

socket

Description

If the socket is in CLOSE or CLOSE_WAIT we shouldnot close the connection if there is still somedata pending.

Must be called with sk_callback_lock.

voidiscsi_sw_tcp_write_space(structsock * sk)¶

Called when more output buffer space is available

Parameters

structsock*sk

socket space is available for

intiscsi_sw_tcp_xmit_segment(struct iscsi_tcp_conn * tcp_conn, struct iscsi_segment * segment)¶

transmit segment

Parameters

structiscsi_tcp_conn*tcp_conn

the iSCSI TCP connection

structiscsi_segment*segment

the buffer to transmnit

Description

This function transmits as much of the buffer asthe network layer will accept, and returns the number ofbytes transmitted.

If CRC hashing is enabled, the function will compute thehash as it goes. When the entire segment has been transmitted,it will retrieve the hash value and send it as well.

intiscsi_sw_tcp_xmit(struct iscsi_conn * conn)¶

TCP transmit

Parameters

structiscsi_conn*conn

iscsi connection

intiscsi_sw_tcp_xmit_qlen(struct iscsi_conn * conn)¶

return the number of bytes queued for xmit

Parameters

structiscsi_conn*conn

iscsi connection

intiscsi_tcp_segment_done(struct iscsi_tcp_conn * tcp_conn, struct iscsi_segment * segment, int recv, unsigned copied)¶

check whether the segment is complete

Parameters

structiscsi_tcp_conn*tcp_conn

iscsi tcp connection

structiscsi_segment*segment

iscsi segment to check

intrecv

set to one of this is called from the recv path

unsignedcopied

number of bytes copied

Description

Check if we’re done receiving this segment. If the receivebuffer is full but we expect more data, move on to thenext entry in the scatterlist.

If the amount of data we received isn’t a multiple of 4,we will transparently receive the pad bytes, too.

This function must be re-entrant.

voidiscsi_tcp_hdr_recv_prep(struct iscsi_tcp_conn * tcp_conn)¶

prep segment for hdr reception

Parameters

structiscsi_tcp_conn*tcp_conn

iscsi connection to prep for

Description

This function always passes NULL for the hash argument, because when thisfunction is called we do not yet know the final size of the header and wantto delay the digest processing until we know that.

voidiscsi_tcp_cleanup_task(struct iscsi_task * task)¶

free tcp_task resources

Parameters

structiscsi_task*task

iscsi task

Description

must be called with session back_lock

intiscsi_tcp_recv_segment_is_hdr(struct iscsi_tcp_conn * tcp_conn)¶

tests if we are reading in a header

Parameters

structiscsi_tcp_conn*tcp_conn

iscsi tcp conn

Description

returns non zero if we are currently processing or setup to processa header.

intiscsi_tcp_recv_skb(struct iscsi_conn * conn, structsk_buff * skb, unsigned int offset, bool offloaded, int * status)¶

Process skb

Parameters

structiscsi_conn*conn

iscsi connection

structsk_buff*skb

network buffer with header and/or data segment

unsignedintoffset

offset in skb

booloffloaded

bool indicating if transfer was offloaded

int*status

iscsi TCP status result

Description

Will return status of transfer instatus. And will returnnumber of bytes copied.

intiscsi_tcp_task_init(struct iscsi_task * task)¶

Initialize iSCSI SCSI_READ or SCSI_WRITE commands

Parameters

structiscsi_task*task

scsi command task

intiscsi_tcp_task_xmit(struct iscsi_task * task)¶

xmit normal PDU task

Parameters

structiscsi_task*task

iscsi command task

Description

We’re expected to return 0 when everything was transmitted successfully,-EAGAIN if there’s still data in the queue, or != 0 for any other kindof error.