Definition:

struct scsi_vpd {    struct rcu_head rcu;    int len;    unsigned char   data[];};

Members

rcu

Forkfree_rcu().

len

Length in bytes ofdata.

data

VPD data as defined in various T10 SCSI standard documents.

Parameters

sdev

thestructscsi_device to use as a cursor

shost

thestructscsi_host to iterate over

Description

Iterator that returns each device attached toshost. This looptakes a reference on each device and releases it at the end. Ifyou break out of the loop, you must call scsi_device_put(sdev).

Parameters

sdev

thestructscsi_device to use as a cursor

shost

thestructscsi_host to iterate over

Description

Iterator that returns each device attached toshost. It does _not_take a reference on the scsi_device, so the whole loop must beprotected by shost->host_lock.

Note

The only reason to use this is because you need to access thedevice list in interrupt context. Otherwise you really want to useshost_for_each_device instead.

Parameters

structscsi_device*sdev

SCSI device to examine

Description

A pseudo SCSI device can be used to allocate SCSI commands but does not showup in sysfs. Additionally, the logical unit information in*sdev is made up.

This function tests the LUN number instead of comparingsdev withsdev->host->pseudo_sdev because this function may be called beforesdev->host->pseudo_sdev has been initialized.

Parameters

structscsi_device*sdev

thestructscsi_device to test

Description

If the ‘try_vpd_pages’ flag is set it takes precedence.Otherwise we will assume VPD pages are supported if theSCSI level is at least SPC-3 and ‘skip_vpd_pages’ is not set.

Parameters

structscsi_device*sdev

SCSI Device in question

intdepth

number of commands allowed to be queued to the driver

Description

Sets the device queue depth and returns the new value.

Parameters

structscsi_device*sdev

SCSI Device in question

intdepth

Current number of outstanding SCSI commands on this device,not counting the one returned as QUEUE_FULL.

Description

This function will track successive QUEUE_FULL events on a

specific SCSI device to determine if and when there is aneed to adjust the queue depth on the device.

Lock Status: None held on entry

Return

• 0 - No change needed

• >0 - Adjust queue depth to this new depth,

• -1 - Drop back to untagged operation using host->cmd_per_lun as theuntagged command depth

Notes

Low level drivers may call this at any time and we will do

“The Right Thing.” We are interrupt context safe.

Parameters

structscsi_device*sdev

The device to ask

u8page

Which Vital Product Data to return

unsignedchar*buf

where to store the VPD

intbuf_len

number of bytes in the VPD buffer area

Description

SCSI devices may optionally supply Vital Product Data. Each ‘page’of VPD is defined in the appropriate SCSI document (eg SPC, SBC).If the device supports this VPD page, this routine fillsbufwith the data from that page and return 0. If the VPD page is notsupported or its content cannot be retrieved, -EINVAL is returned.

Parameters

structscsi_device*sdev

scsi device to query

unsignedchar*buffer

scratch buffer (must be at least 20 bytes long)

unsignedintlen

length of buffer

unsignedcharopcode

opcode for the command to look up

unsignedshortsa

service action for the command to look up

Description

Uses the REPORT SUPPORTED OPERATION CODES to check support for thecommand identified withopcode andsa. If the command does nothave a service action,sa must be 0. Returns -EINVAL if RSOC fails,0 if the command is not supported and 1 if the device claims tosupport the command.

Parameters

structscsi_device*sdev

device to get a reference to

Description

Gets a reference to the scsi_device and increments the use countof the underlying LLDD module. You must hold host_lock of theparent Scsi_Host or already have a reference when calling this.

This will fail if a device is deleted or cancelled, or when the LLD moduleis in the process of being unloaded.

Parameters

structscsi_device*sdev

device to release a reference on.

Description

Release a reference to the scsi_device and decrements the usecount of the underlying LLDD module. The device is freed once the lastuser vanishes.

Parameters

structscsi_target*starget

target whose devices we want to iterate over.

void*data

Opaque passed to each function call.

void(*fn)(structscsi_device*,void*)

Function to call on each device

Description

This traverses over each device ofstarget. The devices havea reference that must be released by scsi_host_put when breakingout of the loop.

Parameters

structscsi_target*starget

target whose devices we want to iterate over.

void*data

parameter for callbackfn()

void(*fn)(structscsi_device*,void*)

callback function that is invoked for each device

Description

This traverses over each device ofstarget. It does _not_take a reference on the scsi_device, so the whole loop must beprotected by shost->host_lock.

Note

The only reason why drivers would want to use this is becausethey need to access the device list in irq context. Otherwise youreally want to use starget_for_each_device instead.

Parameters

structscsi_target*starget

SCSI target pointer

u64lun

SCSI Logical Unit Number

Description

Looks up the scsi_device with the specifiedlun for a givenstarget. The returned scsi_device does not have an additionalreference. You must hold the host’s host_lock over this call andany access to the returned scsi_device. A scsi_device in stateSDEV_DEL is skipped.

Note

The only reason why drivers should use this is becausethey need to access the device list in irq context. Otherwise youreally want to use scsi_device_lookup_by_target instead.

Parameters

structscsi_target*starget

SCSI target pointer

u64lun

SCSI Logical Unit Number

Description

Looks up the scsi_device with the specifiedlun for a givenstarget. The returned scsi_device has an additional reference thatneeds to be released with scsi_device_put once you’re done with it.

Parameters

structScsi_Host*shost

SCSI host pointer

uintchannel

SCSI channel (zero if only one channel)

uintid

SCSI target number (physical unit number)

u64lun

SCSI Logical Unit Number

Description

Looks up the scsi_device with the specifiedchannel,id,lunfor a given host. The returned scsi_device does not have an additionalreference. You must hold the host’s host_lock over this call and any accessto the returned scsi_device.

Note

The only reason why drivers would want to use this is becausethey need to access the device list in irq context. Otherwise youreally want to use scsi_device_lookup instead.

Parameters

structScsi_Host*shost

SCSI host pointer

uintchannel

SCSI channel (zero if only one channel)

uintid

SCSI target number (physical unit number)

u64lun

SCSI Logical Unit Number

Description

Looks up the scsi_device with the specifiedchannel,id,lunfor a given host. The returned scsi_device has an additional reference thatneeds to be released with scsi_device_put once you’re done with it.

Parameters

structgendisk*dev

from this device

Description

Reads the first sector from the device and returns0x42 bytes

starting at offset0x1be.

Return

partition table in kmalloc(GFP_KERNEL) memory, or NULL on error.

Parameters

structgendisk*disk

gendisk of the disk to parse

sector_tcapacity

size of the disk in sectors

intgeom[3]

output in form of [hds, cylinders, sectors]

Description

Determine the BIOS mapping/geometry used to create the partitiontable, storing the results ingeom.

Return

false on failure,true on success.

Parameters

structgendisk*disk

which device

sector_tcapacity

size of the disk in sectors

int*ip

return value: ip[0]=heads, ip[1]=sectors, ip[2]=cylinders

Description

determine the BIOS mapping/geometry used for a drive in a

SCSI-CAM system, storing the results in ip as requiredby the HDIO_GETGEO ioctl().

Return

-1 on failure, 0 on success.

Parameters

structScsi_Host*shost

SCSI host to invoke error handling on.

Description

Schedule SCSI EH without scmd.

Parameters

structscsi_device*sdev

Device on which we are performing recovery.

Description

We block until the host is out of error recovery, and then check tosee whether the host or the device is offline.

Return value:

0 when dev was taken offline by error recovery. 1 OK to proceed.

Parameters

structscsi_cmnd*scmd

Cmd to have sense checked.

Description

Return value:

SUCCESS or FAILED or NEEDS_RETRY or ADD_TO_MLQUEUE

Notes

When a deferred error is detected the current command hasnot been executed and needs retrying.

Parameters

structscsi_cmnd*scmd

SCSI command structure to hijack

structscsi_eh_save*ses

structure to save restore information

unsignedchar*cmnd

CDB to send. Can be NULL if no new cmnd is needed

intcmnd_size

size in bytes ofcmnd (must be <= MAX_COMMAND_SIZE)

unsignedsense_bytes

size of sense data to copy. or 0 (if != 0cmnd is ignored)

Description

This function is used to save a scsi command information before re-executionas part of the error recovery process. Ifsense_bytes is 0 the commandsent must be one that does not transfer any data. Ifsense_bytes != 0cmnd is ignored and this functions sets up a REQUEST_SENSE commandand cmnd buffers to readsense_bytes intoscmd->sense_buffer.

Parameters

structscsi_cmnd*scmd

SCSI command structure to restore

structscsi_eh_save*ses

saved information from a coresponding call to scsi_eh_prep_cmnd

Description

Undo any damage done by abovescsi_eh_prep_cmnd().

Parameters

structscsi_cmnd*scmd

Original SCSI cmd that eh has finished.

structlist_head*done_q

Queue for processed commands.

Notes

We don’t want to use the normal command completion while we are arestill handling errors - it may cause other commands to be queued,and that would disturb what we are doing. Thus we really want tokeep a list of pending commands for final completion, and once weare ready to leave error handling we handle completion for real.

Parameters

structlist_head*work_q

Queue of commands to process.

structlist_head*done_q

Queue of processed commands.

Description

See if we need to request sense information. if so, then get itnow, so we have a better idea of what to do.

Notes

This has the unfortunate side effect that if a shost adapter doesnot automatically request sense information, we end up shuttingit down before we request it.

All drivers should request sense information internally these days,so for now all I have to say is tough noogies if you end up in here.

XXX: Long term this code should go away, but that needs an audit of

all LLDDs first.

Parameters

structScsi_Host*shost

host to be recovered.

structlist_head*work_q

list_head for pending commands.

structlist_head*done_q

list_head for processed commands.

Parameters

structlist_head*done_q

list_head of processed commands.

Parameters

structScsi_Host*shost

Host in question

intchannel

channel on which reset was observed.

Description

Utility function used by low-level drivers to report thatthey have observed a bus reset on the bus being handled.

Lock status: Host lock must be held.

Return

Nothing

Notes

This only needs to be called if the reset is one which

originates from an unknown location. Resets originatedby the mid-level itself don’t need to call this, but thereshould be no harm.

The main purpose of this is to make sure that a CHECK_CONDITIONis properly treated.

Parameters

structScsi_Host*shost

Host in question

intchannel

channel on which reset was observed

inttarget

target on which reset was observed

Description

Utility function used by low-level drivers to report thatthey have observed a device reset on the device being handled.

Lock status: Host lock must be held

Return

Nothing

Notes

This only needs to be called if the reset is one which

originates from an unknown location. Resets originatedby the mid-level itself don’t need to call this, but thereshould be no harm.

The main purpose of this is to make sure that a CHECK_CONDITIONis properly treated.

Parameters

constu8*sense_buffer

byte array of sense data

intsb_len

number of valid bytes in sense_buffer

u64*info_out

pointer to 64 integer where 8 or 4 byte informationfield will be placed if found.

Description

Return value:

true if information field found, false if not found.

Parameters

intcompatible

if true, null terminate short strings. Otherwise space pad.

char*vendor

vendor string

char*model

model (product) string

char*strflags

integer string

blist_flags_tflags

if strflags NULL, use this flag value

enumscsi_devinfo_keykey

specify list to use

Description

Create and add one dev_info entry forvendor,model,strflags orflag in list specified bykey. Ifcompatible,add to the tail of the list, do not space pad, and setdevinfo->compatible. The scsi_static_device_list entries areadded withcompatible 1 andclfags NULL.

Return

0 OK, -error on failure.

Parameters

structscsi_device*sdev

scsi_device to get flags for

constunsignedchar*vendor

vendor name

constunsignedchar*model

model name

enumscsi_devinfo_keykey

list to look up

Description

Search the scsi_dev_info_list specified bykey for an entrymatchingvendor andmodel, if found, return the matchingflags value, else return the host or global default settings.Called during scan time.

Parameters

enumscsi_devinfo_keykey

key of the list to add

constchar*name

Name of the list to add (for /proc/scsi/device_info)

Description

Adds the requested list, returns zero on success, -EEXIST if thekey is already registered to a list, or other error on failure.

Parameters

enumscsi_devinfo_keykey

key of the list to destroy

Description

Iterates over the entire list first, freeing all the values, thenfrees the list itself. Returns 0 on success or -EINVAL if the keycan’t be found.

Parameters

structscsi_device*sdev

target scsi device

charstate

removal state to set (prevent or allow)

Return

• 0 ifsdev is not removable or not lockable or successful.

• non-0 is a SCSI result code if > 0 or kernel error code if < 0.

• Setssdev->locked to the new state on success.

Parameters

unsignedchar*cmd

SCSI command to check

boolopen_for_write

is the file / block device opened for writing?

Description

Only a subset of commands are allowed for unprivileged users. Commands usedto format the media, update the firmware, etc. are not permitted.

Return

true if the cmd is allowed, otherwisefalse.

Parameters

structscsi_device*sdev

scsi device receiving ioctl

boolopen_for_write

is the file / block device opened for writing?

intcmd

which ioctl is it

void__user*arg

data associated with ioctl

Description

Thescsi_ioctl() function differs from most ioctls in that itdoes not take a major/minor number as the dev field. Rather, it takesa pointer to astructscsi_device.

Return

varies depending on thecmd

Parameters

structscsi_device*sdev

target scsi device

intcmd

which ioctl is it

boolndelay

no delay (non-blocking)

Description

We can process a reset even when a device isn’t fully operable.

Return

0 on success, <0 error code.

Parameters

structscsi_failures*failures

structscsi_failures with specific failure modes set

Parameters

structscsi_device*sdev

scsi_device

constunsignedchar*cmd

scsi command

blk_opf_topf

block layer request cmd_flags

void*buffer

data buffer

unsignedintbufflen

len of buffer

inttimeout

request timeout in HZ

intml_retries

number of times SCSI midlayer will retry request

conststructscsi_exec_args*args

Optional args. Seestructdefinition for field descriptions

Description

Returns the scsi_cmnd result field if a command was executed, or a negativeLinux error code if we didn’t get that far.

Parameters

structscsi_cmnd*cmd

SCSI command data structure to initialize.

Description

Initializescmd->sdb and alsocmd->prot_sdb if data integrity is enabledforcmd.

Return

• BLK_STS_OK - on success

• BLK_STS_RESOURCE - if the failure is retryable

• BLK_STS_IOERR - if the failure is fatal

Parameters

structrequest_queue*q

the device’s request queue

blk_opf_topf

the request operation code

blk_mq_req_flags_tflags

block layer allocation flags

Return

structrequest pointer on success orNULL on failure

Parameters

structscsi_device*sdev

SCSI device from which to allocate the command

enumdma_data_directiondata_direction

Data direction for the allocated command

blk_mq_req_flags_tflags

request allocation flags, e.g. BLK_MQ_REQ_RESERVED orBLK_MQ_REQ_NOWAIT.

Description

Allocates a SCSI command for internal LLDD use.

Parameters

structscsi_cmnd*scmd

SCSI command to be freed

Parameters

structrequest_queue*q

The request queue to return the sdev from

Description

Return the sdev associated with a request queue or NULL if therequest_queue does not reference a SCSI device.

Parameters

structScsi_Host*shost

host in question

Description

There is no timer nor any other means by which the requests get unblockedother than the low-level driver callingscsi_unblock_requests().

Parameters

structScsi_Host*shost

host in question

Description

There is no timer nor any other means by which the requests get unblockedother than the low-level driver callingscsi_unblock_requests(). This is doneas an API function so that changes to the internals of the scsi mid-layerwon’t require wholesale changes to drivers that use this feature.

Parameters

structscsi_device*sdev

SCSI device to be queried

intpf

Page format bit (1 == standard, 0 == vendor specific)

intsp

Save page bit (0 == don’t save, 1 == save)

unsignedchar*buffer

request buffer (may not be smaller than eight bytes)

intlen

length of request buffer.

inttimeout

command timeout

intretries

number of retries before failing

structscsi_mode_data*data

returns a structure abstracting the mode header data

structscsi_sense_hdr*sshdr

place to put sense data (or NULL if no sense to be collected).must be SCSI_SENSE_BUFFERSIZE big.

Description

Returns zero if successful; negative error number or scsistatus on error

Parameters

structscsi_device*sdev

SCSI device to be queried

intdbd

set to prevent mode sense from returning block descriptors

intmodepage

mode page being requested

intsubpage

sub-page of the mode page being requested

unsignedchar*buffer

request buffer (may not be smaller than eight bytes)

intlen

length of request buffer.

inttimeout

command timeout

intretries

number of retries before failing

structscsi_mode_data*data

returns a structure abstracting the mode header data

structscsi_sense_hdr*sshdr

place to put sense data (or NULL if no sense to be collected).must be SCSI_SENSE_BUFFERSIZE big.

Description

Returns zero if successful, or a negative error number on failure

Parameters

structscsi_device*sdev

scsi device to change the state of.

inttimeout

command timeout

intretries

number of retries before failing

structscsi_sense_hdr*sshdr

outpout pointer for decoded sense information.

Description

Returns zero if successful or an error if TUR failed. Forremovable media, UNIT_ATTENTION sets ->changed flag.

Parameters

structscsi_device*sdev

scsi device to change the state of.

enumscsi_device_statestate

state to change to.

Description

Returns zero if successful or an error if the requestedtransition is illegal.

Parameters

structscsi_device*sdev

scsi_device event occurred on

structscsi_event*evt

event to send

Description

Assert scsi device event asynchronously.

Parameters

enumscsi_device_eventevt_type

type of event to allocate

gfp_tgfpflags

GFP flags for allocation

Description

Allocates and returns a new scsi_event.

Parameters

structscsi_device*sdev

scsi_device event occurred on

enumscsi_device_eventevt_type

type of event to send

gfp_tgfpflags

GFP flags for allocation

Description

Assert scsi device event asynchronously, given an event type.

Parameters

structscsi_device*sdev

scsi device to quiesce.

Description

This works by trying to transition to the SDEV_QUIESCE state(which must be a legal transition). When the device is in thisstate, only power management requests will be accepted, all others willbe deferred.

Must be called with user context, may sleep.

Returns zero if successful or an error if not.

Parameters

structscsi_device*sdev

scsi device to resume.

Description

Moves the device from quiesced back to running and restarts thequeues.

Must be called with user context, may sleep.

Parameters

structscsi_device*sdev

device to block

Description

Pause SCSI command processing on the specified device. Does not sleep.

Returns zero if successful or a negative error code upon failure.

Notes

This routine transitions the device to the SDEV_BLOCK state (which must bea legal transition). When the device is in this state, command processingis paused until the device leaves the SDEV_BLOCK state. See alsoscsi_internal_device_unblock_nowait().

Parameters

structscsi_device*sdev

device to resume

enumscsi_device_statenew_state

state to set the device to after unblocking

Description

Restart the device queue for a previously suspended SCSI device. Does notsleep.

Returns zero if successful or a negative error code upon failure.

Notes

This routine transitions the device to the SDEV_RUNNING state or to one ofthe offline states (which must be a legal transition) allowing the midlayerto goose the queue for this device.

Parameters

structScsi_Host*shost

the Scsi_Host to which this device belongs

structdevice*dev

a parent device of one or more scsi_target devices

Description

Iterate over all children ofdev, which should be scsi_target devices,and switch all subordinate scsi devices to SDEV_BLOCK state. Wait forongoingscsi_queue_rq() calls to finish. May sleep.

Note

dev must not itself be a scsi_target device.

Parameters

structScsi_Host*shost

device to block

Description

Pause SCSI command processing for all logical units associated with the SCSIhost and wait until pendingscsi_queue_rq() calls have finished.

Returns zero if successful or a negative error code upon failure.

Parameters

structscatterlist*sgl

scatter-gather list

intsg_count

number of segments in sg

size_t*offset

offset in bytes into sg, on return offset into the mapped area

size_t*len

bytes to map, on return number of bytes mapped

Description

Returns virtual address of the start of the mapped page

Parameters

void*virt

virtual address to be unmapped

Parameters

structscsi_device*sdev

SCSI device

char*id

buffer for the identification

size_tid_len

length of the buffer

Description

Copies a unique device identification intoid basedon the information in the VPD page 0x83 of the device.The string will be formatted as a SCSI name string.

Returns the length of the identification or error on failure.If the identifier is longer than the supplied buffer the actualidentifier length is returned and the buffer is not zero-padded.

Parameters

structscsi_device*sdev

SCSI device

int*rel_id

pointer to return relative target port in if notNULL

Description

Returns the Target Port Group identifier from the informationfrom VPD page 0x83 of the device.Optionally setsrel_id to the relative target port on success.

Return

the identifier or error on failure.

Parameters

structscsi_cmnd*scmd

scsi command for which the sense should be formatted

intdesc

Sense format (non-zero == descriptor format,0 == fixed format)

u8key

Sense key

u8asc

Additional sense code

u8ascq

Additional sense code qualifier

Parameters

structscsi_cmnd*cmd

scsi command

Description

Returns the number of sg lists actually used, zero if the sg listsis NULL, or -ENOMEM if the mapping failed.

Parameters

structscsi_cmnd*cmd

scsi command

Definition:

struct scsi_proc_entry {    struct list_head        entry;    const struct scsi_host_template *sht;    struct proc_dir_entry   *proc_dir;    unsigned int            present;};

Members

entry

entry in scsi_proc_list.

sht

SCSI host template associated with the procfs directory.

proc_dir

procfs directory associated with the SCSI host template.

present

Number of SCSI hosts instantiated forsht.

Parameters

conststructscsi_host_template*sht

SCSI host template pointer.

Parameters

conststructscsi_host_template*sht

owner of this directory

Description

Sets sht->proc_dir to the new directory.

Parameters

conststructscsi_host_template*sht

owner of directory

Parameters

structScsi_Host*shost

host to add

Parameters

structScsi_Host*shost

which host

Parameters

structdevice*dev

A scsi device

void*data

structseq_file to output to.

Description

prints Host, Channel, Id, Lun, Vendor, Model, Rev, Type,and revision.

Parameters

uinthost

user-supplied decimal integer

uintchannel

user-supplied decimal integer

uintid

user-supplied decimal integer

uintlun

user-supplied decimal integer

Description

called by writing “scsi add-single-device” to /proc/scsi/scsi.

doesscsi_host_lookup() and eitheruser_scan() if that transporttype supports it, or elsescsi_scan_host_selected()

Note

this seems to be aimed exclusively at SCSI parallel busses.

Parameters

uinthost

user-supplied decimal integer

uintchannel

user-supplied decimal integer

uintid

user-supplied decimal integer

uintlun

user-supplied decimal integer

Description

called by writing “scsi remove-single-device” to/proc/scsi/scsi. Does ascsi_device_lookup() andscsi_remove_device()

Parameters

structfile*file

not used

constchar__user*buf

buffer to write

size_tlength

length of buf, at most PAGE_SIZE

loff_t*ppos

not used

Description

this provides a legacy mechanism to add or remove devices byHost, Channel, ID, and Lun. To use,“echo ‘scsi add-single-device 0 1 2 3’ > /proc/scsi/scsi” or“echo ‘scsi remove-single-device 0 1 2 3’ > /proc/scsi/scsi” with“0 1 2 3” replaced by the Host, Channel, Id, and Lun.

Note

this seems to be aimed at parallel SCSI. Most modern busses (USB,SATA, Firewire, Fibre Channel, etc) dynamically assign these values toprovide a unique identifier and nothing more.

Parameters

structinode*inode

not used

structfile*file

passed tosingle_open()

Description

Associates proc_scsi_show with this file

Parameters

void

no arguments

Parameters

void

no arguments

Parameters

structsk_buff*skb

socket receive buffer

Description

Extracts message from a receive buffer.

Validates message header and calls appropriate transport message handler

Parameters

void

no arguments

Parameters

void

no arguments

Parameters

unsignedchar*s

INQUIRY result string to sanitize

intlen

length of the string

Description

The SCSI spec says that INQUIRY vendor, product, and revisionstrings must consist entirely of graphic ASCII characters,padded on the right with spaces. Since not all devices obeythis rule, we will replace non-graphic or non-ASCII characterswith spaces. Exception: a NUL character is interpreted as astring terminator, so all the following characters are set tospaces.

Parameters

structScsi_Host*host

theScsi_Host instance where the device is located

uintchannel

target channel number (rarely other than0)

uinttarget

target id number

u64lun

LUN of target device

Description

Probe for a specific LUN and add it if found.

Notes

This call is usually performed internally during a SCSIbus scan when an HBA is added (i.e.scsi_scan_host()). So itshould only be called if the HBA becomes aware of a new SCSIdevice (LU) afterscsi_scan_host() has completed. If successfulthis call can lead tosdev_init() andsdev_configure() callbacksinto the LLD.

Return

0 on success or negative error code on failure

Parameters

structdevice*parent

host to scan

unsignedintchannel

channel to scan

unsignedintid

target id to scan

u64lun

Specific LUN to scan or SCAN_WILD_CARD

enumscsi_scan_moderescan

passed to LUN scanning routines; SCSI_SCAN_INITIAL forno rescan, SCSI_SCAN_RESCAN to rescan existing LUNs,and SCSI_SCAN_MANUAL to force scanning even if‘scan=manual’ is set.

Description

Scan the target id onparent,channel, andid. Scan at least LUN 0,and possibly all LUNs on the target id.

First try a REPORT LUN scan, if that does not scan the target, do asequential scan of LUNs on the target id.

Parameters

structScsi_Host*shost

adapter to scan

Notes

Should be called afterscsi_add_host()

Parameters

structscsi_device*sdev

scsi_device to unregister

Parameters

structdevice*dev

generic starget or parent of generic stargets to be removed

Note

This is slightly racy. It is possible that if the userrequests the addition of another device then the target won’t beremoved.

Parameters

structScsi_Host*shost

a pointer to a scsi host to remove

Parameters

structScsi_Host*shost

scsi host pointer to add

structdevice*dev

astructdevice of type scsi class

structdevice*dma_dev

dma device for the host

Note

You rarely need to worry about this unless you’re in avirtualised host environments, so use the simplerscsi_add_host()function instead.

Return value:

0 on success / != 0 for error

Parameters

conststructscsi_host_template*sht

pointer to scsi host template

intprivsize

extra bytes to allocate for driver

Note

Allocate a new Scsi_Host and perform basic initialization.The host is not published to the scsi midlayer until scsi_add_hostis called.

Return value:

Pointer to a new Scsi_Host

Parameters

unsignedinthostnum

host number to locate

Description

Return value:

A pointer to located Scsi_Host or NULL.

The caller must do ascsi_host_put() to drop the referencethatscsi_host_get() took. Theput_device() below droppedthe reference fromclass_find_device().

Parameters

structScsi_Host*shost

Pointer to Scsi_Host to inc.

Parameters

structScsi_Host*shost

Pointer to Scsi_Host

Parameters

structScsi_Host*shost

Pointer to Scsi_Host to dec.

Parameters

structScsi_Host*shost

Pointer to Scsi_Host.

structwork_struct*work

Work to queue for execution.

Description

Return value:

1 - work queued for execution0 - work is already queued-EINVAL - work queue doesn’t exist

Parameters

structScsi_Host*shost

Pointer to Scsi_Host.

Parameters

structScsi_Host*shost

Scsi Host on which commands should be terminated

enumscsi_host_statusstatus

Status to be set for the terminated commands

Description

There is no protection against modification of the numberof outstanding commands. It is the responsibility of thecaller to ensure that concurrent I/O submission and/orcompletion is stopped when calling this function.

Parameters

structScsi_Host*shost

Pointer to Scsi_Host.

bool(*fn)(structscsi_cmnd*,void*)

Function to call on each busy command

void*priv

Data pointer passed tofn

Description

If locking against concurrent command completions is requiredithas to be provided by the caller

Parameters

unsignedtype

type number to look up

Parameters

structscsi_lun*scsilun

structscsi_lun to be converted.

Description

Convertscsilun from astructscsi_lun to a four-byte host byte-orderedinteger, and return the result. The caller must check fortruncation before using this function.

Notes

For a description of the LUN format, post SCSI-3 see the SCSIArchitecture Model, for SCSI-3 see the SCSI Controller Commands.

Given astructscsi_lun of: d2 04 0b 03 00 00 00 00, this functionreturns the integer: 0x0b03d204

This encoding will return a standard integer LUN for LUNs smallerthan 256, which typically use a single level LUN structure withaddressing method 0.

Parameters

u64lun

integer to be reverted

structscsi_lun*scsilun

structscsi_lun to be set.

Description

Reverts the functionality of the scsilun_to_int, which packedan 8-byte lun value into an int. This routine unpacks the intback into the lun value.

Notes

Given an integer : 0x0b03d204, this function returns astructscsi_lun of: d2 04 0b 03 00 00 00 00

Parameters

constu8*sense_buffer

byte array containing sense data returned by device

intsb_len

number of valid bytes in sense_buffer

structscsi_sense_hdr*sshdr

pointer to instance of structure that commonelements are written to.

Notes

The “main elements” from sense data are: response_code, sense_key,asc, ascq and additional_length (only for descriptor format).

Typically this function can be called after a device hasresponded to a SCSI command with the CHECK_CONDITION status.

Return value:

true if valid sense data information found, else false;

Parameters

constu8*sense_buffer

byte array of descriptor format sense data

intsb_len

number of valid bytes in sense_buffer

intdesc_type

value of descriptor type to find(e.g. 0 -> information)

Notes

only valid when sense data is in descriptor format

Return value:

pointer to start of (first) descriptor if found else NULL

Parameters

intdesc

Sense format (non-zero == descriptor format,0 == fixed format)

u8*buf

Where to build sense data

u8key

Sense key

u8asc

Additional sense code

u8ascq

Additional sense code qualifier

Parameters

u8*buf

Where to build sense data

intbuf_len

buffer length

u64info

64-bit information value to be set

Description

Return value:

0 on success or -EINVAL for invalid sense buffer length

Parameters

u8*buf

Where to build sense data

intbuf_len

buffer length

u16fp

field pointer to be set

u8bp

bit pointer to be set

boolcd

command/data bit

Description

Return value:

0 on success or -EINVAL for invalid sense buffer length

Parameters

void

no arguments

Notes

We could have inlined this, but it would have required fc_event_seq tobe exposed. For now, live with the subroutine call.Atomic used to avoid lock/unlock...

Parameters

structScsi_Host*shost

host the event occurred on

u32event_number

fc event number obtained fromget_fc_event_number()

enumfc_host_event_codeevent_code

fc_host event being posted

u32data_len

amount, in bytes, of event data

char*data_buf

pointer to event data

u64vendor_id

value for Vendor id

Notes

This routine assumes no locks are held on entry.

Parameters

structScsi_Host*shost

host the event occurred on

u32event_number

fc event number obtained fromget_fc_event_number()

enumfc_host_event_codeevent_code

fc_host event being posted

u32event_data

32bits of data for the event being posted

Notes

This routine assumes no locks are held on entry.

Parameters

structScsi_Host*shost

host the event occurred on

u32event_number

fc event number obtained fromget_fc_event_number()

u32data_len

amount, in bytes, of vendor unique data

char*data_buf

pointer to vendor unique data

u64vendor_id

Vendor id

Notes

This routine assumes no locks are held on entry.

Parameters

structScsi_Host*shost

host the fc_rport is associated with

u64wwpn

wwpn of the fc_rport device

Notes

This routine assumes no locks are held on entry.

Parameters

structScsi_Host*shost

host the FPIN was received on

u32fpin_len

length of FPIN payload, in bytes

char*fpin_buf

pointer to FPIN payload

u8event_acknowledge

1, if LLDD handles this event.

Notes

This routine assumes no locks are held on entry.

Parameters

structscsi_cmnd*scmd

The SCSI command which timed out

Description

This routine protects against error handlers getting invoked while arport is in a blocked state, typically due to a temporarily loss ofconnectivity. If the error handlers are allowed to proceed, requeststo abort i/o, reset the target, etc will likely fail as there is no wayto communicate with the device to perform the requested function. Thesefailures may result in the midlayer taking the device offline, requiringmanual intervention to restore operation.

This routine, called whenever an i/o times out, validates the state ofthe underlying rport. If the rport is blocked, it returnsEH_RESET_TIMER, which will continue to reschedule the timeout.Eventually, either the device will return, or devloss_tmo will fire,and when the timeout then fires, it will be handled normally.If the rport is not blocked, normal error handling continues.

Notes

This routine assumes no locks are held on entry.

Parameters

structScsi_Host*shost

WhichScsi_Host

Description

This routine is expected to be called immediately preceding thea driver’s call toscsi_remove_host().

WARNING: A driver utilizing the fc_transport, which fails to call

this routine prior toscsi_remove_host(), will leave danglingobjects in /sys/class/fc_remote_ports. Access to any of theseobjects can result in a system crash !!!

Notes

This routine assumes no locks are held on entry.

Parameters

structScsi_Host*shost

scsi host the remote port is connected to.

intchannel

Channel on shost port connected to.

structfc_rport_identifiers*ids

The world wide names, fc address, and FC4 portroles for the remote port.

Description

The LLDD calls this routine to notify the transport of the existenceof a remote port. The LLDD provides the unique identifiers (wwpn,wwn)of the port, it’s FC address (port_id), and the FC4 roles that areactive for the port.

For ports that are FCP targets (aka scsi targets), the FC transportmaintains consistent target id bindings on behalf of the LLDD.A consistent target id binding is an assignment of a target id toa remote port identifier, which persists while the scsi host isattached. The remote port can disappear, then later reappear, andit’s target id assignment remains the same. This allows for shiftsin FC addressing (if binding by wwpn or wwnn) with no apparentchanges to the scsi subsystem which is based on scsi host number andtarget id values. Bindings are only valid during the attachment ofthe scsi host. If the host detaches, then later re-attaches, targetid bindings may change.

This routine is responsible for returning a remote port structure.The routine will search the list of remote ports it maintainsinternally on behalf of consistent target id mappings. If found, theremote port structure will be reused. Otherwise, a new remote portstructure will be allocated.

Whenever a remote port is allocated, a new fc_remote_port classdevice is created.

Should not be called from interrupt context.

Notes

This routine assumes no locks are held on entry.

Parameters

structfc_rport*rport

The remote port that no longer exists

Description

The LLDD calls this routine to notify the transport that a remoteport is no longer part of the topology. Note: Although a portmay no longer be part of the topology, it may persist in the remoteports displayed by the fc_host. We do this under 2 conditions:

1. If the port was a scsi target, we delay its deletion by “blocking” it.This allows the port to temporarily disappear, then reappear withoutdisrupting the SCSI device tree attached to it. During the “blocked”period the port will still exist.

2. If the port was a scsi target and disappears for longer than weexpect, we’ll delete the port and the tear down the SCSI device treeattached to it. However, we want to semi-persist the target id assignedto that port if it eventually does exist. The port structure willremain (although with minimal information) so that the target idbindings also remain.

If the remote port is not an FCP Target, it will be fully torn downand deallocated, including the fc_remote_port class device.

If the remote port is an FCP Target, the port will be placed in atemporary blocked state. From the LLDD’s perspective, the rport nolonger exists. From the SCSI midlayer’s perspective, the SCSI targetexists, but all sdevs on it are blocked from further I/O. The followingis then expected.

If the remote port does not return (signaled by a LLDD call tofc_remote_port_add()) within the dev_loss_tmo timeout, then thescsi target is removed - killing all outstanding i/o and removing thescsi devices attached to it. The port structure will be marked NotPresent and be partially cleared, leaving only enough information torecognize the remote port relative to the scsi target id binding ifit later appears. The port will remain as long as there is a validbinding (e.g. until the user changes the binding type or unloads thescsi host with the binding).

If the remote port returns within the dev_loss_tmo value (and matchesaccording to the target id binding type), the port structure will bereused. If it is no longer a SCSI target, the target will be torndown. If it continues to be a SCSI target, then the target will beunblocked (allowing i/o to be resumed), and a scan will be activatedto ensure that all luns are detected.

Called from normal process context only - cannot be called from interrupt.

Notes

This routine assumes no locks are held on entry.

Parameters

structfc_rport*rport

The remote port that changed.

u32roles

New roles for this port.

Description

The LLDD calls this routine to notify the transport that theroles on a remote port may have changed. The largest effect of this isif a port now becomes a FCP Target, it must be allocated ascsi target id. If the port is no longer a FCP target, anyscsi target id value assigned to it will persist in case therole changes back to include FCP Target. No changes in the scsimidlayer will be invoked if the role changes (in the expectationthat the role will be resumed. If it doesn’t normal error processingwill take place).

Should not be called from interrupt context.

Notes

This routine assumes no locks are held on entry.

Parameters

structfc_rport*rport

Remote port that scsi_eh is trying to recover.

Description

This routine can be called from a FC LLD scsi_eh callback. Itblocks the scsi_eh thread until the fc_rport leaves theFC_PORTSTATE_BLOCKED, or the fast_io_fail_tmo fires. This isnecessary to avoid the scsi_eh failing recovery actions for blockedrports which would lead to offlined SCSI devices.

Return

0 if the fc_rport left the state FC_PORTSTATE_BLOCKED.FAST_IO_FAIL if the fast_io_fail_tmo fired, this should bepassed back to scsi_eh.

Parameters

structscsi_cmnd*cmnd

SCSI command that scsi_eh is trying to recover

Description

This routine can be called from a FC LLD scsi_eh callback. Itblocks the scsi_eh thread until the fc_rport leaves theFC_PORTSTATE_BLOCKED, or the fast_io_fail_tmo fires. This isnecessary to avoid the scsi_eh failing recovery actions for blockedrports which would lead to offlined SCSI devices.

Return

0 if the fc_rport left the state FC_PORTSTATE_BLOCKED.FAST_IO_FAIL if the fast_io_fail_tmo fired, this should bepassed back to scsi_eh.

Parameters

structScsi_Host*shost

scsi host the virtual port is connected to.

intchannel

channel on shost port connected to.

structfc_vport_identifiers*ids

The world wide names, FC4 port roles, etc forthe virtual port.

Notes

This routine assumes no locks are held on entry.

Parameters

structfc_vport*vport

fc_vport to be terminated

Description

Calls the LLDDvport_delete() function, then deallocates and removesthe vport from the shost and object tree.

Notes

This routine assumes no locks are held on entry.

Parameters

u64handle

endpoint handle

Description

Caller must do a iscsi_put_endpoint.

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

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

Parameters

structScsi_Host*shost

pointer to host data

constvoid*data

pointer to data containing value to use for comparison

device_match_tfn

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

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

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