James Bottomley

James.Bottomley@hansenpartnership.com

Rob Landley

rob@landley.net

2007 Linux Foundation This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. For more details see the file COPYING in the source distribution of Linux. Once upon a time, the Small Computer Systems Interface defined both a parallel I/O bus and a data protocol to connect a wide variety of peripherals (disk drives, tape drives, modems, printers, scanners, optical drives, test equipment, and medical devices) to a host computer. Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen out of use, the SCSI command set is more widely used than ever to communicate with devices over a number of different busses. The SCSI protocol is a big-endian peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 bytes long, often followed by an associated data payload. SCSI commands can be transported over just about any kind of bus, and are the default protocol for storage devices attached to USB, SATA, SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also commonly exchanged over Infiniband, I20, TCP/IP (iSCSI), even Parallel ports. The SCSI subsystem uses a three layer design, with upper, mid, and low layers. Every operation involving the SCSI subsystem (such as reading a sector from a disk) uses one driver at each of the 3 levels: one upper layer driver, one lower layer driver, and the SCSI midlayer. The SCSI upper layer provides the interface between userspace and the kernel, in the form of block and char device nodes for I/O and ioctl(). The SCSI lower layer contains drivers for specific hardware devices. In between is the SCSI mid-layer, analogous to a network routing layer such as the IPv4 stack. The SCSI mid-layer routes a packet based data protocol between the upper layer's /dev nodes and the corresponding devices in the lower layer. It manages command queues, provides error handling and power management functions, and responds to ioctl() requests. The upper layer supports the user-kernel interface by providing device nodes. sd (sd_mod.o) sr (sr_mod.o) st (st.o) sg (sg.o) ch (ch.c) Kernel Hackers Manual July 2017 shost_for_each_device 9 4.1.27 shost_for_each_device iterate over all devices of a host shost_for_each_device sdev shost sdev the struct scsi_device to use as a cursor shost the struct scsi_host to iterate over Iterator that returns each device attached to shost. This loop takes a reference on each device and releases it at the end. If you break out of the loop, you must call scsi_device_put(sdev). Kernel Hackers Manual July 2017 __shost_for_each_device 9 4.1.27 __shost_for_each_device iterate over all devices of a host (UNLOCKED) __shost_for_each_device sdev shost sdev the struct scsi_device to use as a cursor shost the struct scsi_host to iterate over Iterator that returns each device attached to shost. It does _not_ take a reference on the scsi_device, so the whole loop must be protected by shost->host_lock. The only reason to use this is because you need to access the device list in interrupt context. Otherwise you really want to use shost_for_each_device instead. Main file for the SCSI midlayer. Kernel Hackers Manual July 2017 scsi_device_type 9 4.1.27 scsi_device_type Return 17 char string indicating device type. const char * scsi_device_type unsigned type type type number to look up Kernel Hackers Manual July 2017 scsi_cmd_get_serial 9 4.1.27 scsi_cmd_get_serial Assign a serial number to a command void scsi_cmd_get_serial struct Scsi_Host * host struct scsi_cmnd * cmd host the scsi host cmd command to assign serial number to a serial number identifies a request for error recovery and debugging purposes. Protected by the Host_Lock of host. Kernel Hackers Manual July 2017 scsi_change_queue_depth 9 4.1.27 scsi_change_queue_depth change a device's queue depth int scsi_change_queue_depth struct scsi_device * sdev int depth sdev SCSI Device in question depth number of commands allowed to be queued to the driver Sets the device queue depth and returns the new value. Kernel Hackers Manual July 2017 scsi_track_queue_full 9 4.1.27 scsi_track_queue_full track QUEUE_FULL events to adjust queue depth int scsi_track_queue_full struct scsi_device * sdev int depth sdev SCSI Device in question depth Current number of outstanding SCSI commands on this device, not counting the one returned as QUEUE_FULL. This function will track successive QUEUE_FULL events on a specific SCSI device to determine if and when there is a need to adjust the queue depth on the device. 0 - No change needed, >0 - Adjust queue depth to this new depth, -1 - Drop back to untagged operation using host->cmd_per_lun as the untagged command depth None held on entry Low level drivers may call this at any time and we will do The Right Thing. We are interrupt context safe. Kernel Hackers Manual July 2017 scsi_get_vpd_page 9 4.1.27 scsi_get_vpd_page Get Vital Product Data from a SCSI device int scsi_get_vpd_page struct scsi_device * sdev u8 page unsigned char * buf int buf_len sdev The device to ask page Which Vital Product Data to return buf where to store the VPD buf_len number of bytes in the VPD buffer area 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 returns a pointer to a buffer containing the data from that page. The caller is responsible for calling kfree on this pointer when it is no longer needed. If we cannot retrieve the VPD page this routine returns NULL. Kernel Hackers Manual July 2017 scsi_report_opcode 9 4.1.27 scsi_report_opcode Find out if a given command opcode is supported int scsi_report_opcode struct scsi_device * sdev unsigned char * buffer unsigned int len unsigned char opcode sdev scsi device to query buffer scratch buffer (must be at least 20 bytes long) len length of buffer opcode opcode for command to look up Uses the REPORT SUPPORTED OPERATION CODES to look up the given opcode. Returns -EINVAL if RSOC fails, 0 if the command opcode is unsupported and 1 if the device claims to support the command. Kernel Hackers Manual July 2017 scsi_device_get 9 4.1.27 scsi_device_get get an additional reference to a scsi_device int scsi_device_get struct scsi_device * sdev sdev device to get a reference to Gets a reference to the scsi_device and increments the use count of the underlying LLDD module. You must hold host_lock of the parent Scsi_Host or already have a reference when calling this. This will fail if a device is deleted or cancelled, or when the LLD module is in the process of being unloaded. Kernel Hackers Manual July 2017 scsi_device_put 9 4.1.27 scsi_device_put release a reference to a scsi_device void scsi_device_put struct scsi_device * sdev sdev device to release a reference on. Release a reference to the scsi_device and decrements the use count of the underlying LLDD module. The device is freed once the last user vanishes. Kernel Hackers Manual July 2017 starget_for_each_device 9 4.1.27 starget_for_each_device helper to walk all devices of a target void starget_for_each_device struct scsi_target * starget void * data void (*fn) struct scsi_device *, void * starget target whose devices we want to iterate over. data Opaque passed to each function call. fn Function to call on each device This traverses over each device of starget. The devices have a reference that must be released by scsi_host_put when breaking out of the loop. Kernel Hackers Manual July 2017 __starget_for_each_device 9 4.1.27 __starget_for_each_device helper to walk all devices of a target (UNLOCKED) void __starget_for_each_device struct scsi_target * starget void * data void (*fn) struct scsi_device *, void * starget target whose devices we want to iterate over. data parameter for callback fn() fn callback function that is invoked for each device This traverses over each device of starget. It does _not_ take a reference on the scsi_device, so the whole loop must be protected by shost->host_lock. The only reason why drivers would want to use this is because they need to access the device list in irq context. Otherwise you really want to use starget_for_each_device instead. Kernel Hackers Manual July 2017 __scsi_device_lookup_by_target 9 4.1.27 __scsi_device_lookup_by_target find a device given the target (UNLOCKED) struct scsi_device * __scsi_device_lookup_by_target struct scsi_target * starget u64 lun starget SCSI target pointer lun SCSI Logical Unit Number Looks up the scsi_device with the specified lun for a given starget. The returned scsi_device does not have an additional reference. You must hold the host's host_lock over this call and any access to the returned scsi_device. A scsi_device in state SDEV_DEL is skipped. The only reason why drivers should use this is because they need to access the device list in irq context. Otherwise you really want to use scsi_device_lookup_by_target instead. Kernel Hackers Manual July 2017 scsi_device_lookup_by_target 9 4.1.27 scsi_device_lookup_by_target find a device given the target struct scsi_device * scsi_device_lookup_by_target struct scsi_target * starget u64 lun starget SCSI target pointer lun SCSI Logical Unit Number Looks up the scsi_device with the specified lun for a given starget. The returned scsi_device has an additional reference that needs to be released with scsi_device_put once you're done with it. Kernel Hackers Manual July 2017 __scsi_device_lookup 9 4.1.27 __scsi_device_lookup find a device given the host (UNLOCKED) struct scsi_device * __scsi_device_lookup struct Scsi_Host * shost uint channel uint id u64 lun shost SCSI host pointer channel SCSI channel (zero if only one channel) id SCSI target number (physical unit number) lun SCSI Logical Unit Number Looks up the scsi_device with the specified channel, id, lun for a given host. The returned scsi_device does not have an additional reference. You must hold the host's host_lock over this call and any access to the returned scsi_device. The only reason why drivers would want to use this is because they need to access the device list in irq context. Otherwise you really want to use scsi_device_lookup instead. Kernel Hackers Manual July 2017 scsi_device_lookup 9 4.1.27 scsi_device_lookup find a device given the host struct scsi_device * scsi_device_lookup struct Scsi_Host * shost uint channel uint id u64 lun shost SCSI host pointer channel SCSI channel (zero if only one channel) id SCSI target number (physical unit number) lun SCSI Logical Unit Number Looks up the scsi_device with the specified channel, id, lun for a given host. The returned scsi_device has an additional reference that needs to be released with scsi_device_put once you're done with it. SCSI Common Access Method support functions, for use with HDIO_GETGEO, etc. Kernel Hackers Manual July 2017 scsi_bios_ptable 9 4.1.27 scsi_bios_ptable Read PC partition table out of first sector of device. unsigned char * scsi_bios_ptable struct block_device * dev dev from this device Reads the first sector from the device and returns 0x42 bytes starting at offset 0x1be. partition table in kmalloc(GFP_KERNEL) memory, or NULL on error. Kernel Hackers Manual July 2017 scsicam_bios_param 9 4.1.27 scsicam_bios_param Determine geometry of a disk in cylinders/heads/sectors. int scsicam_bios_param struct block_device * bdev sector_t capacity int * ip bdev which device capacity size of the disk in sectors ip return value: ip[0]=heads, ip[1]=sectors, ip[2]=cylinders determine the BIOS mapping/geometry used for a drive in a SCSI-CAM system, storing the results in ip as required by the HDIO_GETGEO ioctl. -1 on failure, 0 on success. Kernel Hackers Manual July 2017 scsi_partsize 9 4.1.27 scsi_partsize Parse cylinders/heads/sectors from PC partition table int scsi_partsize unsigned char * buf unsigned long capacity unsigned int * cyls unsigned int * hds unsigned int * secs buf partition table, see scsi_bios_ptable capacity size of the disk in sectors cyls put cylinders here hds put heads here secs put sectors here determine the BIOS mapping/geometry used to create the partition table, storing the results in *cyls, *hds, and *secs -1 on failure, 0 on success. Common SCSI error/timeout handling routines. Kernel Hackers Manual July 2017 scsi_schedule_eh 9 4.1.27 scsi_schedule_eh schedule EH for SCSI host void scsi_schedule_eh struct Scsi_Host * shost shost SCSI host to invoke error handling on. Schedule SCSI EH without scmd. Kernel Hackers Manual July 2017 scsi_block_when_processing_errors 9 4.1.27 scsi_block_when_processing_errors Prevent cmds from being queued. int scsi_block_when_processing_errors struct scsi_device * sdev sdev Device on which we are performing recovery. We block until the host is out of error recovery, and then check to see whether the host or the device is offline. 0 when dev was taken offline by error recovery. 1 OK to proceed. Kernel Hackers Manual July 2017 scsi_eh_prep_cmnd 9 4.1.27 scsi_eh_prep_cmnd Save a scsi command info as part of error recovery void scsi_eh_prep_cmnd struct scsi_cmnd * scmd struct scsi_eh_save * ses unsigned char * cmnd int cmnd_size unsigned sense_bytes scmd SCSI command structure to hijack ses structure to save restore information cmnd CDB to send. Can be NULL if no new cmnd is needed cmnd_size size in bytes of cmnd (must be <= BLK_MAX_CDB) sense_bytes size of sense data to copy. or 0 (if != 0 cmnd is ignored) This function is used to save a scsi command information before re-execution as part of the error recovery process. If sense_bytes is 0 the command sent must be one that does not transfer any data. If sense_bytes != 0 cmnd is ignored and this functions sets up a REQUEST_SENSE command and cmnd buffers to read sense_bytes into scmd->sense_buffer. Kernel Hackers Manual July 2017 scsi_eh_restore_cmnd 9 4.1.27 scsi_eh_restore_cmnd Restore a scsi command info as part of error recovery void scsi_eh_restore_cmnd struct scsi_cmnd * scmd struct scsi_eh_save * ses scmd SCSI command structure to restore ses saved information from a coresponding call to scsi_eh_prep_cmnd Undo any damage done by above scsi_eh_prep_cmnd. Kernel Hackers Manual July 2017 scsi_eh_finish_cmd 9 4.1.27 scsi_eh_finish_cmd Handle a cmd that eh is finished with. void scsi_eh_finish_cmd struct scsi_cmnd * scmd struct list_head * done_q scmd Original SCSI cmd that eh has finished. done_q Queue for processed commands. We don't want to use the normal command completion while we are are still handling errors - it may cause other commands to be queued, and that would disturb what we are doing. Thus we really want to keep a list of pending commands for final completion, and once we are ready to leave error handling we handle completion for real. Kernel Hackers Manual July 2017 scsi_eh_get_sense 9 4.1.27 scsi_eh_get_sense Get device sense data. int scsi_eh_get_sense struct list_head * work_q struct list_head * done_q work_q Queue of commands to process. done_q Queue of processed commands. See if we need to request sense information. if so, then get it now, so we have a better idea of what to do. This has the unfortunate side effect that if a shost adapter does not automatically request sense information, we end up shutting it 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. Long term this code should go away, but that needs an audit of all LLDDs first. Kernel Hackers Manual July 2017 scsi_eh_ready_devs 9 4.1.27 scsi_eh_ready_devs check device ready state and recover if not. void scsi_eh_ready_devs struct Scsi_Host * shost struct list_head * work_q struct list_head * done_q shost host to be recovered. work_q list_head for pending commands. done_q list_head for processed commands. Kernel Hackers Manual July 2017 scsi_eh_flush_done_q 9 4.1.27 scsi_eh_flush_done_q finish processed commands or retry them. void scsi_eh_flush_done_q struct list_head * done_q done_q list_head of processed commands. Kernel Hackers Manual July 2017 scsi_ioctl_reset 9 4.1.27 scsi_ioctl_reset int scsi_ioctl_reset struct scsi_device * dev int __user * arg dev scsi_device to operate on arg reset type (see sg.h) Kernel Hackers Manual July 2017 scsi_normalize_sense 9 4.1.27 scsi_normalize_sense normalize main elements from either fixed or descriptor sense data format into a common format. bool scsi_normalize_sense const u8 * sense_buffer int sb_len struct scsi_sense_hdr * sshdr sense_buffer byte array containing sense data returned by device sb_len number of valid bytes in sense_buffer sshdr pointer to instance of structure that common elements are written to. 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 has responded to a SCSI command with the CHECK_CONDITION status. true if valid sense data information found, else false; Kernel Hackers Manual July 2017 scsi_sense_desc_find 9 4.1.27 scsi_sense_desc_find search for a given descriptor type in descriptor sense data format. const u8 * scsi_sense_desc_find const u8 * sense_buffer int sb_len int desc_type sense_buffer byte array of descriptor format sense data sb_len number of valid bytes in sense_buffer desc_type value of descriptor type to find (e.g. 0 -> information) only valid when sense data is in descriptor format pointer to start of (first) descriptor if found else NULL Kernel Hackers Manual July 2017 scsi_get_sense_info_fld 9 4.1.27 scsi_get_sense_info_fld get information field from sense data (either fixed or descriptor format) int scsi_get_sense_info_fld const u8 * sense_buffer int sb_len u64 * info_out sense_buffer byte array of sense data sb_len number of valid bytes in sense_buffer info_out pointer to 64 integer where 8 or 4 byte information field will be placed if found. 1 if information field found, 0 if not found. Kernel Hackers Manual July 2017 scsi_build_sense_buffer 9 4.1.27 scsi_build_sense_buffer build sense data in a buffer void scsi_build_sense_buffer int desc u8 * buf u8 key u8 asc u8 ascq desc Sense format (non zero == descriptor format, 0 == fixed format) buf Where to build sense data key Sense key asc Additional sense code ascq Additional sense code qualifier Manage scsi_dev_info_list, which tracks blacklisted and whitelisted devices. Kernel Hackers Manual July 2017 scsi_dev_info_list_add 9 4.1.27 scsi_dev_info_list_add add one dev_info list entry. int scsi_dev_info_list_add int compatible char * vendor char * model char * strflags int flags compatible if true, null terminate short strings. Otherwise space pad. vendor vendor string model model (product) string strflags integer string flags if strflags NULL, use this flag value Create and add one dev_info entry for vendor, model, strflags or flag. If compatible, add to the tail of the list, do not space pad, and set devinfo->compatible. The scsi_static_device_list entries are added with compatible 1 and clfags NULL. 0 OK, -error on failure. Kernel Hackers Manual July 2017 scsi_dev_info_list_add_str 9 4.1.27 scsi_dev_info_list_add_str parse dev_list and add to the scsi_dev_info_list. int scsi_dev_info_list_add_str char * dev_list dev_list string of device flags to add Parse dev_list, and add entries to the scsi_dev_info_list. dev_list is of the form vendor:product:flag,vendor:product:flag. dev_list is modified via strsep. Can be called for command line addition, for proc or mabye a sysfs interface. 0 if OK, -error on failure. Kernel Hackers Manual July 2017 scsi_get_device_flags 9 4.1.27 scsi_get_device_flags get device specific flags from the dynamic device list. int scsi_get_device_flags struct scsi_device * sdev const unsigned char * vendor const unsigned char * model sdev scsi_device to get flags for vendor vendor name model model name Search the global scsi_dev_info_list (specified by list zero) for an entry matching vendor and model, if found, return the matching flags value, else return the host or global default settings. Called during scan time. Kernel Hackers Manual July 2017 scsi_exit_devinfo 9 4.1.27 scsi_exit_devinfo remove /proc/scsi/device_info & the scsi_dev_info_list void scsi_exit_devinfo void void no arguments Kernel Hackers Manual July 2017 scsi_init_devinfo 9 4.1.27 scsi_init_devinfo set up the dynamic device list. int scsi_init_devinfo void void no arguments Add command line entries from scsi_dev_flags, then add scsi_static_device_list entries to the scsi device info list. Handle ioctl() calls for SCSI devices. Kernel Hackers Manual July 2017 scsi_ioctl 9 4.1.27 scsi_ioctl Dispatch ioctl to scsi device int scsi_ioctl struct scsi_device * sdev int cmd void __user * arg sdev scsi device receiving ioctl cmd which ioctl is it arg data associated with ioctl The scsi_ioctl function differs from most ioctls in that it does not take a major/minor number as the dev field. Rather, it takes a pointer to a struct scsi_device. SCSI queuing library. Kernel Hackers Manual July 2017 scsi_execute 9 4.1.27 scsi_execute insert request and wait for the result int scsi_execute struct scsi_device * sdev const unsigned char * cmd int data_direction void * buffer unsigned bufflen unsigned char * sense int timeout int retries u64 flags int * resid sdev scsi device cmd scsi command data_direction data direction buffer data buffer bufflen len of buffer sense optional sense buffer timeout request timeout in seconds retries number of times to retry request flags or into request flags; resid optional residual length returns the req->errors value which is the scsi_cmnd result field. Kernel Hackers Manual July 2017 scsi_mode_select 9 4.1.27 scsi_mode_select issue a mode select int scsi_mode_select struct scsi_device * sdev int pf int sp int modepage unsigned char * buffer int len int timeout int retries struct scsi_mode_data * data struct scsi_sense_hdr * sshdr sdev SCSI device to be queried pf Page format bit (1 == standard, 0 == vendor specific) sp Save page bit (0 == don't save, 1 == save) modepage mode page being requested buffer request buffer (may not be smaller than eight bytes) len length of request buffer. timeout command timeout retries number of retries before failing data returns a structure abstracting the mode header data sshdr place to put sense data (or NULL if no sense to be collected). must be SCSI_SENSE_BUFFERSIZE big. Returns zero if successful; negative error number or scsi status on error Kernel Hackers Manual July 2017 scsi_mode_sense 9 4.1.27 scsi_mode_sense issue a mode sense, falling back from 10 to six bytes if necessary. int scsi_mode_sense struct scsi_device * sdev int dbd int modepage unsigned char * buffer int len int timeout int retries struct scsi_mode_data * data struct scsi_sense_hdr * sshdr sdev SCSI device to be queried dbd set if mode sense will allow block descriptors to be returned modepage mode page being requested buffer request buffer (may not be smaller than eight bytes) len length of request buffer. timeout command timeout retries number of retries before failing data returns a structure abstracting the mode header data sshdr place to put sense data (or NULL if no sense to be collected). must be SCSI_SENSE_BUFFERSIZE big. Returns zero if unsuccessful, or the header offset (either 4 or 8 depending on whether a six or ten byte command was issued) if successful. Kernel Hackers Manual July 2017 scsi_test_unit_ready 9 4.1.27 scsi_test_unit_ready test if unit is ready int scsi_test_unit_ready struct scsi_device * sdev int timeout int retries struct scsi_sense_hdr * sshdr_external sdev scsi device to change the state of. timeout command timeout retries number of retries before failing sshdr_external Optional pointer to struct scsi_sense_hdr for returning sense. Make sure that this is cleared before passing in. Returns zero if unsuccessful or an error if TUR failed. For removable media, UNIT_ATTENTION sets ->changed flag. Kernel Hackers Manual July 2017 scsi_device_set_state 9 4.1.27 scsi_device_set_state Take the given device through the device state model. int scsi_device_set_state struct scsi_device * sdev enum scsi_device_state state sdev scsi device to change the state of. state state to change to. Returns zero if unsuccessful or an error if the requested transition is illegal. Kernel Hackers Manual July 2017 sdev_evt_send 9 4.1.27 sdev_evt_send send asserted event to uevent thread void sdev_evt_send struct scsi_device * sdev struct scsi_event * evt sdev scsi_device event occurred on evt event to send Assert scsi device event asynchronously. Kernel Hackers Manual July 2017 sdev_evt_alloc 9 4.1.27 sdev_evt_alloc allocate a new scsi event struct scsi_event * sdev_evt_alloc enum scsi_device_event evt_type gfp_t gfpflags evt_type type of event to allocate gfpflags GFP flags for allocation Allocates and returns a new scsi_event. Kernel Hackers Manual July 2017 sdev_evt_send_simple 9 4.1.27 sdev_evt_send_simple send asserted event to uevent thread void sdev_evt_send_simple struct scsi_device * sdev enum scsi_device_event evt_type gfp_t gfpflags sdev scsi_device event occurred on evt_type type of event to send gfpflags GFP flags for allocation Assert scsi device event asynchronously, given an event type. Kernel Hackers Manual July 2017 scsi_device_quiesce 9 4.1.27 scsi_device_quiesce Block user issued commands. int scsi_device_quiesce struct scsi_device * sdev sdev scsi device to quiesce. This works by trying to transition to the SDEV_QUIESCE state (which must be a legal transition). When the device is in this state, only special requests will be accepted, all others will be deferred. Since special requests may also be requeued requests, a successful return doesn't guarantee the device will be totally quiescent. Must be called with user context, may sleep. Returns zero if unsuccessful or an error if not. Kernel Hackers Manual July 2017 scsi_device_resume 9 4.1.27 scsi_device_resume Restart user issued commands to a quiesced device. void scsi_device_resume struct scsi_device * sdev sdev scsi device to resume. Moves the device from quiesced back to running and restarts the queues. Must be called with user context, may sleep. Kernel Hackers Manual July 2017 scsi_internal_device_block 9 4.1.27 scsi_internal_device_block internal function to put a device temporarily into the SDEV_BLOCK state int scsi_internal_device_block struct scsi_device * sdev sdev device to block Block request made by scsi lld's to temporarily stop all scsi commands on the specified device. Called from interrupt or normal process context. Returns zero if successful or error if not This routine transitions the device to the SDEV_BLOCK state (which must be a legal transition). When the device is in this state, all commands are deferred until the scsi lld reenables the device with scsi_device_unblock or device_block_tmo fires. Kernel Hackers Manual July 2017 scsi_internal_device_unblock 9 4.1.27 scsi_internal_device_unblock resume a device after a block request int scsi_internal_device_unblock struct scsi_device * sdev enum scsi_device_state new_state sdev device to resume new_state state to set devices to after unblocking Called by scsi lld's or the midlayer to restart the device queue for the previously suspended scsi device. Called from interrupt or normal process context. Returns zero if successful or error if not. This routine transitions the device to the SDEV_RUNNING state or to one of the offline states (which must be a legal transition) allowing the midlayer to goose the queue for this device. Kernel Hackers Manual July 2017 scsi_kmap_atomic_sg 9 4.1.27 scsi_kmap_atomic_sg find and atomically map an sg-elemnt void * scsi_kmap_atomic_sg struct scatterlist * sgl int sg_count size_t * offset size_t * len sgl scatter-gather list sg_count number of segments in sg offset offset in bytes into sg, on return offset into the mapped area len bytes to map, on return number of bytes mapped Returns virtual address of the start of the mapped page Kernel Hackers Manual July 2017 scsi_kunmap_atomic_sg 9 4.1.27 scsi_kunmap_atomic_sg atomically unmap a virtual address, previously mapped with scsi_kmap_atomic_sg void scsi_kunmap_atomic_sg void * virt virt virtual address to be unmapped SCSI library functions depending on DMA (map and unmap scatter-gather lists). Kernel Hackers Manual July 2017 scsi_dma_map 9 4.1.27 scsi_dma_map perform DMA mapping against command's sg lists int scsi_dma_map struct scsi_cmnd * cmd cmd scsi command Returns the number of sg lists actually used, zero if the sg lists is NULL, or -ENOMEM if the mapping failed. Kernel Hackers Manual July 2017 scsi_dma_unmap 9 4.1.27 scsi_dma_unmap unmap command's sg lists mapped by scsi_dma_map void scsi_dma_unmap struct scsi_cmnd * cmd cmd scsi command The file drivers/scsi/scsi_module.c contains legacy support for old-style host templates. It should never be used by any new driver. The functions in this file provide an interface between the PROC file system and the SCSI device drivers It is mainly used for debugging, statistics and to pass information directly to the lowlevel driver. I.E. plumbing to manage /proc/scsi/* Kernel Hackers Manual July 2017 scsi_proc_hostdir_add 9 4.1.27 scsi_proc_hostdir_add Create directory in /proc for a scsi host void scsi_proc_hostdir_add struct scsi_host_template * sht sht owner of this directory Sets sht->proc_dir to the new directory. Kernel Hackers Manual July 2017 scsi_proc_hostdir_rm 9 4.1.27 scsi_proc_hostdir_rm remove directory in /proc for a scsi host void scsi_proc_hostdir_rm struct scsi_host_template * sht sht owner of directory Kernel Hackers Manual July 2017 scsi_proc_host_add 9 4.1.27 scsi_proc_host_add Add entry for this host to appropriate /proc dir void scsi_proc_host_add struct Scsi_Host * shost shost host to add Kernel Hackers Manual July 2017 scsi_proc_host_rm 9 4.1.27 scsi_proc_host_rm remove this host's entry from /proc void scsi_proc_host_rm struct Scsi_Host * shost shost which host Kernel Hackers Manual July 2017 proc_print_scsidevice 9 4.1.27 proc_print_scsidevice return data about this host int proc_print_scsidevice struct device * dev void * data dev A scsi device data struct seq_file to output to. prints Host, Channel, Id, Lun, Vendor, Model, Rev, Type, and revision. Kernel Hackers Manual July 2017 scsi_add_single_device 9 4.1.27 scsi_add_single_device Respond to user request to probe for/add device int scsi_add_single_device uint host uint channel uint id uint lun host user-supplied decimal integer channel user-supplied decimal integer id user-supplied decimal integer lun user-supplied decimal integer called by writing scsi add-single-device to /proc/scsi/scsi. does scsi_host_lookup and either user_scan if that transport type supports it, or else scsi_scan_host_selected this seems to be aimed exclusively at SCSI parallel busses. Kernel Hackers Manual July 2017 scsi_remove_single_device 9 4.1.27 scsi_remove_single_device Respond to user request to remove a device int scsi_remove_single_device uint host uint channel uint id uint lun host user-supplied decimal integer channel user-supplied decimal integer id user-supplied decimal integer lun user-supplied decimal integer called by writing scsi remove-single-device to /proc/scsi/scsi. Does a scsi_device_lookup and scsi_remove_device Kernel Hackers Manual July 2017 proc_scsi_write 9 4.1.27 proc_scsi_write handle writes to /proc/scsi/scsi ssize_t proc_scsi_write struct file * file const char __user * buf size_t length loff_t * ppos file not used buf buffer to write length length of buf, at most PAGE_SIZE ppos not used this provides a legacy mechanism to add or remove devices by Host, 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. this seems to be aimed at parallel SCSI. Most modern busses (USB, SATA, Firewire, Fibre Channel, etc) dynamically assign these values to provide a unique identifier and nothing more. Kernel Hackers Manual July 2017 proc_scsi_open 9 4.1.27 proc_scsi_open glue function int proc_scsi_open struct inode * inode struct file * file inode not used file passed to single_open Associates proc_scsi_show with this file Kernel Hackers Manual July 2017 scsi_init_procfs 9 4.1.27 scsi_init_procfs create scsi and scsi/scsi in procfs int scsi_init_procfs void void no arguments Kernel Hackers Manual July 2017 scsi_exit_procfs 9 4.1.27 scsi_exit_procfs Remove scsi/scsi and scsi from procfs void scsi_exit_procfs void void no arguments Infrastructure to provide async events from transports to userspace via netlink, using a single NETLINK_SCSITRANSPORT protocol for all transports. See the original patch submission for more details. Kernel Hackers Manual July 2017 scsi_nl_rcv_msg 9 4.1.27 scsi_nl_rcv_msg Receive message handler. void scsi_nl_rcv_msg struct sk_buff * skb skb socket receive buffer Extracts message from a receive buffer. Validates message header and calls appropriate transport message handler Kernel Hackers Manual July 2017 scsi_netlink_init 9 4.1.27 scsi_netlink_init Called by SCSI subsystem to initialize the SCSI transport netlink interface void scsi_netlink_init void void no arguments Kernel Hackers Manual July 2017 scsi_netlink_exit 9 4.1.27 scsi_netlink_exit Called by SCSI subsystem to disable the SCSI transport netlink interface void scsi_netlink_exit void void no arguments Scan a host to determine which (if any) devices are attached. The general scanning/probing algorithm is as follows, exceptions are made to it depending on device specific flags, compilation options, and global variable (boot or module load time) settings. A specific LUN is scanned via an INQUIRY command; if the LUN has a device attached, a scsi_device is allocated and setup for it. For every id of every channel on the given host, start by scanning LUN 0. Skip hosts that don't respond at all to a scan of LUN 0. Otherwise, if LUN 0 has a device attached, allocate and setup a scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN, and scan all of the LUNs returned by the REPORT LUN; else, sequentially scan LUNs up until some maximum is reached, or a LUN is seen that cannot have a device attached to it. Kernel Hackers Manual July 2017 scsi_complete_async_scans 9 4.1.27 scsi_complete_async_scans Wait for asynchronous scans to complete int scsi_complete_async_scans void void no arguments When this function returns, any host which started scanning before this function was called will have finished its scan. Hosts which started scanning after this function was called may or may not have finished. Kernel Hackers Manual July 2017 scsi_unlock_floptical 9 4.1.27 scsi_unlock_floptical unlock device via a special MODE SENSE command void scsi_unlock_floptical struct scsi_device * sdev unsigned char * result sdev scsi device to send command to result area to store the result of the MODE SENSE Send a vendor specific MODE SENSE (not a MODE SELECT) command. Called for BLIST_KEY devices. Kernel Hackers Manual July 2017 scsi_alloc_sdev 9 4.1.27 scsi_alloc_sdev allocate and setup a scsi_Device struct scsi_device * scsi_alloc_sdev struct scsi_target * starget u64 lun void * hostdata starget which target to allocate a scsi_device for lun which lun hostdata usually NULL and set by ->slave_alloc instead Allocate, initialize for io, and return a pointer to a scsi_Device. Stores the shost, channel, id, and lun in the scsi_Device, and adds scsi_Device to the appropriate list. scsi_Device pointer, or NULL on failure. Kernel Hackers Manual July 2017 scsi_target_reap_ref_release 9 4.1.27 scsi_target_reap_ref_release remove target from visibility void scsi_target_reap_ref_release struct kref * kref kref the reap_ref in the target being released Called on last put of reap_ref, which is the indication that no device under this target is visible anymore, so render the target invisible in sysfs. Note: we have to be in user context here because the target reaps should be done in places where the scsi device visibility is being removed. Kernel Hackers Manual July 2017 scsi_alloc_target 9 4.1.27 scsi_alloc_target allocate a new or find an existing target struct scsi_target * scsi_alloc_target struct device * parent int channel uint id parent parent of the target (need not be a scsi host) channel target channel number (zero if no channels) id target id number Return an existing target if one exists, provided it hasn't already gone into STARGET_DEL state, otherwise allocate a new target. The target is returned with an incremented reference, so the caller is responsible for both reaping and doing a last put Kernel Hackers Manual July 2017 scsi_target_reap 9 4.1.27 scsi_target_reap check to see if target is in use and destroy if not void scsi_target_reap struct scsi_target * starget starget target to be checked This is used after removing a LUN or doing a last put of the target it checks atomically that nothing is using the target and removes it if so. Kernel Hackers Manual July 2017 sanitize_inquiry_string 9 4.1.27 sanitize_inquiry_string remove non-graphical chars from an INQUIRY result string void sanitize_inquiry_string unsigned char * s int len s INQUIRY result string to sanitize len length of the string The SCSI spec says that INQUIRY vendor, product, and revision strings must consist entirely of graphic ASCII characters, padded on the right with spaces. Since not all devices obey this rule, we will replace non-graphic or non-ASCII characters with spaces. Exception: a NUL character is interpreted as a string terminator, so all the following characters are set to spaces. Kernel Hackers Manual July 2017 scsi_probe_lun 9 4.1.27 scsi_probe_lun probe a single LUN using a SCSI INQUIRY int scsi_probe_lun struct scsi_device * sdev unsigned char * inq_result int result_len int * bflags sdev scsi_device to probe inq_result area to store the INQUIRY result result_len len of inq_result bflags store any bflags found here Probe the lun associated with req using a standard SCSI INQUIRY; If the INQUIRY is successful, zero is returned and the INQUIRY data is in inq_result; the scsi_level and INQUIRY length are copied to the scsi_device any flags value is stored in *bflags. Kernel Hackers Manual July 2017 scsi_add_lun 9 4.1.27 scsi_add_lun allocate and fully initialze a scsi_device int scsi_add_lun struct scsi_device * sdev unsigned char * inq_result int * bflags int async sdev holds information to be stored in the new scsi_device inq_result holds the result of a previous INQUIRY to the LUN bflags black/white list flag async 1 if this device is being scanned asynchronously Initialize the scsi_device sdev. Optionally set fields based on values in *bflags. could not allocate or setup a scsi_device a new scsi_device was allocated and initialized Kernel Hackers Manual July 2017 scsi_inq_str 9 4.1.27 scsi_inq_str print INQUIRY data from min to max index, strip trailing whitespace unsigned char * scsi_inq_str unsigned char * buf unsigned char * inq unsigned first unsigned end buf Output buffer with at least end-first+1 bytes of space inq Inquiry buffer (input) first Offset of string into inq end Index after last character in inq Kernel Hackers Manual July 2017 scsi_probe_and_add_lun 9 4.1.27 scsi_probe_and_add_lun probe a LUN, if a LUN is found add it int scsi_probe_and_add_lun struct scsi_target * starget u64 lun int * bflagsp struct scsi_device ** sdevp int rescan void * hostdata starget pointer to target device structure lun LUN of target device bflagsp store bflags here if not NULL sdevp probe the LUN corresponding to this scsi_device rescan if nonzero skip some code only needed on first scan hostdata passed to scsi_alloc_sdev Call scsi_probe_lun, if a LUN with an attached device is found, allocate and set it up by calling scsi_add_lun. could not allocate or setup a scsi_device target responded, but no device is attached at the LUN a new scsi_device was allocated and initialized Kernel Hackers Manual July 2017 scsi_sequential_lun_scan 9 4.1.27 scsi_sequential_lun_scan sequentially scan a SCSI target void scsi_sequential_lun_scan struct scsi_target * starget int bflags int scsi_level int rescan starget pointer to target structure to scan bflags black/white list flag for LUN 0 scsi_level Which version of the standard does this device adhere to rescan passed to scsi_probe_add_lun Generally, scan from LUN 1 (LUN 0 is assumed to already have been scanned) to some maximum lun until a LUN is found with no device attached. Use the bflags to figure out any oddities. Modifies sdevscan->lun. Kernel Hackers Manual July 2017 scsi_report_lun_scan 9 4.1.27 scsi_report_lun_scan Scan using SCSI REPORT LUN results int scsi_report_lun_scan struct scsi_target * starget int bflags int rescan starget which target bflags Zero or a mix of BLIST_NOLUN, BLIST_REPORTLUN2, or BLIST_NOREPORTLUN rescan nonzero if we can skip code only needed on first scan Fast scanning for modern (SCSI-3) devices by sending a REPORT LUN command. Scan the resulting list of LUNs by calling scsi_probe_and_add_lun. If BLINK_REPORTLUN2 is set, scan a target that supports more than 8 LUNs even if it's older than SCSI-3. If BLIST_NOREPORTLUN is set, return 1 always. If BLIST_NOLUN is set, return 0 always. If starget->no_report_luns is set, return 1 always. scan completed (or no memory, so further scanning is futile) could not scan with REPORT LUN Kernel Hackers Manual July 2017 scsi_prep_async_scan 9 4.1.27 scsi_prep_async_scan prepare for an async scan struct async_scan_data * scsi_prep_async_scan struct Scsi_Host * shost shost the host which will be scanned a cookie to be passed to scsi_finish_async_scan Tells the midlayer this host is going to do an asynchronous scan. It reserves the host's position in the scanning list and ensures that other asynchronous scans started after this one won't affect the ordering of the discovered devices. Kernel Hackers Manual July 2017 scsi_finish_async_scan 9 4.1.27 scsi_finish_async_scan asynchronous scan has finished void scsi_finish_async_scan struct async_scan_data * data data cookie returned from earlier call to scsi_prep_async_scan All the devices currently attached to this host have been found. This function announces all the devices it has found to the rest of the system. Set up the sysctl entry: "/dev/scsi/logging_level" (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level. SCSI sysfs interface routines. Kernel Hackers Manual July 2017 scsi_remove_device 9 4.1.27 scsi_remove_device unregister a device from the scsi bus void scsi_remove_device struct scsi_device * sdev sdev scsi_device to unregister Kernel Hackers Manual July 2017 scsi_remove_target 9 4.1.27 scsi_remove_target try to remove a target and all its devices void scsi_remove_target struct device * dev dev generic starget or parent of generic stargets to be removed This is slightly racy. It is possible that if the user requests the addition of another device then the target won't be removed. mid to lowlevel SCSI driver interface Kernel Hackers Manual July 2017 scsi_host_set_state 9 4.1.27 scsi_host_set_state Take the given host through the host state model. int scsi_host_set_state struct Scsi_Host * shost enum scsi_host_state state shost scsi host to change the state of. state state to change to. Returns zero if unsuccessful or an error if the requested transition is illegal. Kernel Hackers Manual July 2017 scsi_remove_host 9 4.1.27 scsi_remove_host remove a scsi host void scsi_remove_host struct Scsi_Host * shost shost a pointer to a scsi host to remove Kernel Hackers Manual July 2017 scsi_add_host_with_dma 9 4.1.27 scsi_add_host_with_dma add a scsi host with dma device int scsi_add_host_with_dma struct Scsi_Host * shost struct device * dev struct device * dma_dev shost scsi host pointer to add dev a struct device of type scsi class dma_dev dma device for the host You rarely need to worry about this unless you're in a virtualised host environments, so use the simpler scsi_add_host function instead. 0 on success / != 0 for error Kernel Hackers Manual July 2017 scsi_host_alloc 9 4.1.27 scsi_host_alloc register a scsi host adapter instance. struct Scsi_Host * scsi_host_alloc struct scsi_host_template * sht int privsize sht pointer to scsi host template privsize extra bytes to allocate for driver Allocate a new Scsi_Host and perform basic initialization. The host is not published to the scsi midlayer until scsi_add_host is called. Pointer to a new Scsi_Host Kernel Hackers Manual July 2017 scsi_host_lookup 9 4.1.27 scsi_host_lookup get a reference to a Scsi_Host by host no struct Scsi_Host * scsi_host_lookup unsigned short hostnum hostnum host number to locate A pointer to located Scsi_Host or NULL. The caller must do a scsi_host_put to drop the reference that scsi_host_get took. The put_device below dropped the reference from class_find_device. Kernel Hackers Manual July 2017 scsi_host_get 9 4.1.27 scsi_host_get inc a Scsi_Host ref count struct Scsi_Host * scsi_host_get struct Scsi_Host * shost shost Pointer to Scsi_Host to inc. Kernel Hackers Manual July 2017 scsi_host_put 9 4.1.27 scsi_host_put dec a Scsi_Host ref count void scsi_host_put struct Scsi_Host * shost shost Pointer to Scsi_Host to dec. Kernel Hackers Manual July 2017 scsi_queue_work 9 4.1.27 scsi_queue_work Queue work to the Scsi_Host workqueue. int scsi_queue_work struct Scsi_Host * shost struct work_struct * work shost Pointer to Scsi_Host. work Work to queue for execution. 1 - work queued for execution 0 - work is already queued -EINVAL - work queue doesn't exist Kernel Hackers Manual July 2017 scsi_flush_work 9 4.1.27 scsi_flush_work Flush a Scsi_Host's workqueue. void scsi_flush_work struct Scsi_Host * shost shost Pointer to Scsi_Host. mid to lowlevel SCSI driver interface .//drivers/scsi/constants.c Document generation inconsistency The template for this document tried to insert the structured comment from the file .//drivers/scsi/constants.c at this point, but none was found. This dummy section is inserted to allow generation to continue. Transport classes are service libraries for drivers in the SCSI lower layer, which expose transport attributes in sysfs. The file drivers/scsi/scsi_transport_fc.c defines transport attributes for Fibre Channel. Kernel Hackers Manual July 2017 fc_get_event_number 9 4.1.27 fc_get_event_number Obtain the next sequential FC event number u32 fc_get_event_number void void no arguments We could have inlined this, but it would have required fc_event_seq to be exposed. For now, live with the subroutine call. Atomic used to avoid lock/unlock... Kernel Hackers Manual July 2017 fc_host_post_event 9 4.1.27 fc_host_post_event called to post an even on an fc_host. void fc_host_post_event struct Scsi_Host * shost u32 event_number enum fc_host_event_code event_code u32 event_data shost host the event occurred on event_number fc event number obtained from get_fc_event_number event_code fc_host event being posted event_data 32bits of data for the event being posted This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_host_post_vendor_event 9 4.1.27 fc_host_post_vendor_event called to post a vendor unique event on an fc_host void fc_host_post_vendor_event struct Scsi_Host * shost u32 event_number u32 data_len char * data_buf u64 vendor_id shost host the event occurred on event_number fc event number obtained from get_fc_event_number data_len amount, in bytes, of vendor unique data data_buf pointer to vendor unique data vendor_id Vendor id This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_remove_host 9 4.1.27 fc_remove_host called to terminate any fc_transport-related elements for a scsi host. void fc_remove_host struct Scsi_Host * shost shost Which Scsi_Host This routine is expected to be called immediately preceding the a driver's call to scsi_remove_host. A driver utilizing the fc_transport, which fails to call this routine prior to scsi_remove_host, will leave dangling objects in /sys/class/fc_remote_ports. Access to any of these objects can result in a system crash !!! This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_remote_port_add 9 4.1.27 fc_remote_port_add notify fc transport of the existence of a remote FC port. struct fc_rport * fc_remote_port_add struct Scsi_Host * shost int channel struct fc_rport_identifiers * ids shost scsi host the remote port is connected to. channel Channel on shost port connected to. ids The world wide names, fc address, and FC4 port roles for the remote port. The LLDD calls this routine to notify the transport of the existence of 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 are active for the port. For ports that are FCP targets (aka scsi targets), the FC transport maintains consistent target id bindings on behalf of the LLDD. A consistent target id binding is an assignment of a target id to a remote port identifier, which persists while the scsi host is attached. The remote port can disappear, then later reappear, and it's target id assignment remains the same. This allows for shifts in FC addressing (if binding by wwpn or wwnn) with no apparent changes to the scsi subsystem which is based on scsi host number and target id values. Bindings are only valid during the attachment of the scsi host. If the host detaches, then later re-attaches, target id bindings may change. This routine is responsible for returning a remote port structure. The routine will search the list of remote ports it maintains internally on behalf of consistent target id mappings. If found, the remote port structure will be reused. Otherwise, a new remote port structure will be allocated. Whenever a remote port is allocated, a new fc_remote_port class device is created. Should not be called from interrupt context. This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_remote_port_delete 9 4.1.27 fc_remote_port_delete notifies the fc transport that a remote port is no longer in existence. void fc_remote_port_delete struct fc_rport * rport rport The remote port that no longer exists The LLDD calls this routine to notify the transport that a remote port is no longer part of the topology. Note: Although a port may no longer be part of the topology, it may persist in the remote ports 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 without disrupting 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 we expect, we'll delete the port and the tear down the SCSI device tree attached to it. However, we want to semi-persist the target id assigned to that port if it eventually does exist. The port structure will remain (although with minimal information) so that the target id bindings remails. If the remote port is not an FCP Target, it will be fully torn down and deallocated, including the fc_remote_port class device. If the remote port is an FCP Target, the port will be placed in a temporary blocked state. From the LLDD's perspective, the rport no longer exists. From the SCSI midlayer's perspective, the SCSI target exists, but all sdevs on it are blocked from further I/O. The following is then expected. If the remote port does not return (signaled by a LLDD call to fc_remote_port_add) within the dev_loss_tmo timeout, then the scsi target is removed - killing all outstanding i/o and removing the scsi devices attached ot it. The port structure will be marked Not Present and be partially cleared, leaving only enough information to recognize the remote port relative to the scsi target id binding if it later appears. The port will remain as long as there is a valid binding (e.g. until the user changes the binding type or unloads the scsi host with the binding). If the remote port returns within the dev_loss_tmo value (and matches according to the target id binding type), the port structure will be reused. If it is no longer a SCSI target, the target will be torn down. If it continues to be a SCSI target, then the target will be unblocked (allowing i/o to be resumed), and a scan will be activated to ensure that all luns are detected. Called from normal process context only - cannot be called from interrupt. This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_remote_port_rolechg 9 4.1.27 fc_remote_port_rolechg notifies the fc transport that the roles on a remote may have changed. void fc_remote_port_rolechg struct fc_rport * rport u32 roles rport The remote port that changed. roles New roles for this port. The LLDD calls this routine to notify the transport that the roles on a remote port may have changed. The largest effect of this is if a port now becomes a FCP Target, it must be allocated a scsi target id. If the port is no longer a FCP target, any scsi target id value assigned to it will persist in case the role changes back to include FCP Target. No changes in the scsi midlayer will be invoked if the role changes (in the expectation that the role will be resumed. If it doesn't normal error processing will take place). Should not be called from interrupt context. This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_block_scsi_eh 9 4.1.27 fc_block_scsi_eh Block SCSI eh thread for blocked fc_rport int fc_block_scsi_eh struct scsi_cmnd * cmnd cmnd SCSI command that scsi_eh is trying to recover This routine can be called from a FC LLD scsi_eh callback. It blocks the scsi_eh thread until the fc_rport leaves the FC_PORTSTATE_BLOCKED, or the fast_io_fail_tmo fires. This is necessary to avoid the scsi_eh failing recovery actions for blocked rports which would lead to offlined SCSI devices. 0 if the fc_rport left the state FC_PORTSTATE_BLOCKED. FAST_IO_FAIL if the fast_io_fail_tmo fired, this should be passed back to scsi_eh. Kernel Hackers Manual July 2017 fc_vport_create 9 4.1.27 fc_vport_create Admin App or LLDD requests creation of a vport struct fc_vport * fc_vport_create struct Scsi_Host * shost int channel struct fc_vport_identifiers * ids shost scsi host the virtual port is connected to. channel channel on shost port connected to. ids The world wide names, FC4 port roles, etc for the virtual port. This routine assumes no locks are held on entry. Kernel Hackers Manual July 2017 fc_vport_terminate 9 4.1.27 fc_vport_terminate Admin App or LLDD requests termination of a vport int fc_vport_terminate struct fc_vport * vport vport fc_vport to be terminated Calls the LLDD vport_delete function, then deallocates and removes the vport from the shost and object tree. This routine assumes no locks are held on entry. The file drivers/scsi/scsi_transport_iscsi.c defines transport attributes for the iSCSI class, which sends SCSI packets over TCP/IP connections. Kernel Hackers Manual July 2017 iscsi_create_flashnode_sess 9 4.1.27 iscsi_create_flashnode_sess Add flashnode session entry in sysfs struct iscsi_bus_flash_session * iscsi_create_flashnode_sess struct Scsi_Host * shost int index struct iscsi_transport * transport int dd_size shost pointer to host data index index of flashnode to add in sysfs transport pointer to transport data dd_size total size to allocate Adds a sysfs entry for the flashnode session attributes pointer to allocated flashnode sess on success NULL on failure Kernel Hackers Manual July 2017 iscsi_create_flashnode_conn 9 4.1.27 iscsi_create_flashnode_conn Add flashnode conn entry in sysfs 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 shost pointer to host data fnode_sess pointer to the parent flashnode session entry transport pointer to transport data dd_size total size to allocate Adds a sysfs entry for the flashnode connection attributes pointer to allocated flashnode conn on success NULL on failure Kernel Hackers Manual July 2017 iscsi_is_flashnode_conn_dev 9 4.1.27 iscsi_is_flashnode_conn_dev verify passed device is to be flashnode conn int iscsi_is_flashnode_conn_dev struct device * dev void * data dev device to verify data pointer to data containing value to use for verification Verifies if the passed device is flashnode conn device 1 on success 0 on failure Kernel Hackers Manual July 2017 iscsi_find_flashnode_sess 9 4.1.27 iscsi_find_flashnode_sess finds flashnode session entry struct device * iscsi_find_flashnode_sess struct Scsi_Host * shost void * data int (*fn) struct device *dev, void *data shost pointer to host data data pointer to data containing value to use for comparison fn function pointer that does actual comparison Finds the flashnode session object comparing the data passed using logic defined in passed function pointer pointer to found flashnode session device object on success NULL on failure Kernel Hackers Manual July 2017 iscsi_find_flashnode_conn 9 4.1.27 iscsi_find_flashnode_conn finds flashnode connection entry struct device * iscsi_find_flashnode_conn struct iscsi_bus_flash_session * fnode_sess fnode_sess pointer to parent flashnode session entry Finds the flashnode connection object comparing the data passed using logic defined in passed function pointer pointer to found flashnode connection device object on success NULL on failure Kernel Hackers Manual July 2017 iscsi_destroy_flashnode_sess 9 4.1.27 iscsi_destroy_flashnode_sess destroy flashnode session entry void iscsi_destroy_flashnode_sess struct iscsi_bus_flash_session * fnode_sess fnode_sess pointer to flashnode session entry to be destroyed Deletes the flashnode session entry and all children flashnode connection entries from sysfs Kernel Hackers Manual July 2017 iscsi_destroy_all_flashnode 9 4.1.27 iscsi_destroy_all_flashnode destroy all flashnode session entries void iscsi_destroy_all_flashnode struct Scsi_Host * shost shost pointer to host data Destroys all the flashnode session entries and all corresponding children flashnode connection entries from sysfs Kernel Hackers Manual July 2017 iscsi_scan_finished 9 4.1.27 iscsi_scan_finished helper to report when running scans are done int iscsi_scan_finished struct Scsi_Host * shost unsigned long time shost scsi host time scan run time This function can be used by drives like qla4xxx to report to the scsi layer when the scans it kicked off at module load time are done. Kernel Hackers Manual July 2017 iscsi_block_scsi_eh 9 4.1.27 iscsi_block_scsi_eh block scsi eh until session state has transistioned int iscsi_block_scsi_eh struct scsi_cmnd * cmd cmd scsi cmd passed to scsi eh handler If the session is down this function will wait for the recovery timer to fire or for the session to be logged back in. If the recovery timer fires then FAST_IO_FAIL is returned. The caller should pass this error value to the scsi eh. Kernel Hackers Manual July 2017 iscsi_unblock_session 9 4.1.27 iscsi_unblock_session set a session as logged in and start IO. void iscsi_unblock_session struct iscsi_cls_session * session session iscsi session Mark a session as ready to accept IO. Kernel Hackers Manual July 2017 iscsi_create_session 9 4.1.27 iscsi_create_session create iscsi class session struct iscsi_cls_session * iscsi_create_session struct Scsi_Host * shost struct iscsi_transport * transport int dd_size unsigned int target_id shost scsi host transport iscsi transport dd_size private driver data size target_id which target This can be called from a LLD or iscsi_transport. Kernel Hackers Manual July 2017 iscsi_destroy_session 9 4.1.27 iscsi_destroy_session destroy iscsi session int iscsi_destroy_session struct iscsi_cls_session * session session iscsi_session Can be called by a LLD or iscsi_transport. There must not be any running connections. Kernel Hackers Manual July 2017 iscsi_create_conn 9 4.1.27 iscsi_create_conn create iscsi class connection struct iscsi_cls_conn * iscsi_create_conn struct iscsi_cls_session * session int dd_size uint32_t cid session iscsi cls session dd_size private driver data size cid connection id This can be called from a LLD or iscsi_transport. The connection is child of the session so cid must be unique for all connections on the session. Since we do not support MCS, cid will normally be zero. In some cases for software iscsi we could be trying to preallocate a connection struct in which case there could be two connection structs and cid would be non-zero. Kernel Hackers Manual July 2017 iscsi_destroy_conn 9 4.1.27 iscsi_destroy_conn destroy iscsi class connection int iscsi_destroy_conn struct iscsi_cls_conn * conn conn iscsi cls session This can be called from a LLD or iscsi_transport. Kernel Hackers Manual July 2017 iscsi_session_event 9 4.1.27 iscsi_session_event send session destr. completion event int iscsi_session_event struct iscsi_cls_session * session enum iscsi_uevent_e event session iscsi class session event type of event The file drivers/scsi/scsi_transport_sas.c defines transport attributes for Serial Attached SCSI, a variant of SATA aimed at large high-end systems. The SAS transport class contains common code to deal with SAS HBAs, an aproximated representation of SAS topologies in the driver model, and various sysfs attributes to expose these topologies and management interfaces to userspace. In addition to the basic SCSI core objects this transport class introduces two additional intermediate objects: The SAS PHY as represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or Expander, and the SAS remote PHY represented by struct sas_rphy defines an "incoming" PHY on a SAS Expander or end device. Note that this is purely a software concept, the underlying hardware for a PHY and a remote PHY is the exactly the same. There is no concept of a SAS port in this code, users can see what PHYs form a wide port based on the port_identifier attribute, which is the same for all PHYs in a port. Kernel Hackers Manual July 2017 sas_remove_children 9 4.1.27 sas_remove_children tear down a devices SAS data structures void sas_remove_children struct device * dev dev device belonging to the sas object Removes all SAS PHYs and remote PHYs for a given object Kernel Hackers Manual July 2017 sas_remove_host 9 4.1.27 sas_remove_host tear down a Scsi_Host's SAS data structures void sas_remove_host struct Scsi_Host * shost shost Scsi Host that is torn down Removes all SAS PHYs and remote PHYs for a given Scsi_Host. Must be called just before scsi_remove_host for SAS HBAs. Kernel Hackers Manual July 2017 sas_tlr_supported 9 4.1.27 sas_tlr_supported checking TLR bit in vpd 0x90 unsigned int sas_tlr_supported struct scsi_device * sdev sdev scsi device struct Check Transport Layer Retries are supported or not. If vpd page 0x90 is present, TRL is supported. Kernel Hackers Manual July 2017 sas_disable_tlr 9 4.1.27 sas_disable_tlr setting TLR flags void sas_disable_tlr struct scsi_device * sdev sdev scsi device struct Seting tlr_enabled flag to 0. Kernel Hackers Manual July 2017 sas_enable_tlr 9 4.1.27 sas_enable_tlr setting TLR flags void sas_enable_tlr struct scsi_device * sdev sdev scsi device struct Seting tlr_enabled flag 1. Kernel Hackers Manual July 2017 sas_phy_alloc 9 4.1.27 sas_phy_alloc allocates and initialize a SAS PHY structure struct sas_phy * sas_phy_alloc struct device * parent int number parent Parent device number Phy index Allocates an SAS PHY structure. It will be added in the device tree below the device specified by parent, which has to be either a Scsi_Host or sas_rphy. SAS PHY allocated or NULL if the allocation failed. Kernel Hackers Manual July 2017 sas_phy_add 9 4.1.27 sas_phy_add add a SAS PHY to the device hierarchy int sas_phy_add struct sas_phy * phy phy The PHY to be added Publishes a SAS PHY to the rest of the system. Kernel Hackers Manual July 2017 sas_phy_free 9 4.1.27 sas_phy_free free a SAS PHY void sas_phy_free struct sas_phy * phy phy SAS PHY to free Frees the specified SAS PHY. This function must only be called on a PHY that has not successfully been added using sas_phy_add. Kernel Hackers Manual July 2017 sas_phy_delete 9 4.1.27 sas_phy_delete remove SAS PHY void sas_phy_delete struct sas_phy * phy phy SAS PHY to remove Removes the specified SAS PHY. If the SAS PHY has an associated remote PHY it is removed before. Kernel Hackers Manual July 2017 scsi_is_sas_phy 9 4.1.27 scsi_is_sas_phy check if a struct device represents a SAS PHY int scsi_is_sas_phy const struct device * dev dev device to check 1 if the device represents a SAS PHY, 0 else Kernel Hackers Manual July 2017 sas_port_add 9 4.1.27 sas_port_add add a SAS port to the device hierarchy int sas_port_add struct sas_port * port port port to be added publishes a port to the rest of the system Kernel Hackers Manual July 2017 sas_port_free 9 4.1.27 sas_port_free free a SAS PORT void sas_port_free struct sas_port * port port SAS PORT to free Frees the specified SAS PORT. This function must only be called on a PORT that has not successfully been added using sas_port_add. Kernel Hackers Manual July 2017 sas_port_delete 9 4.1.27 sas_port_delete remove SAS PORT void sas_port_delete struct sas_port * port port SAS PORT to remove Removes the specified SAS PORT. If the SAS PORT has an associated phys, unlink them from the port as well. Kernel Hackers Manual July 2017 scsi_is_sas_port 9 4.1.27 scsi_is_sas_port check if a struct device represents a SAS port int scsi_is_sas_port const struct device * dev dev device to check 1 if the device represents a SAS Port, 0 else Kernel Hackers Manual July 2017 sas_port_get_phy 9 4.1.27 sas_port_get_phy try to take a reference on a port member struct sas_phy * sas_port_get_phy struct sas_port * port port port to check Kernel Hackers Manual July 2017 sas_port_add_phy 9 4.1.27 sas_port_add_phy add another phy to a port to form a wide port void sas_port_add_phy struct sas_port * port struct sas_phy * phy port port to add the phy to phy phy to add When a port is initially created, it is empty (has no phys). All ports must have at least one phy to operated, and all wide ports must have at least two. The current code makes no difference between ports and wide ports, but the only object that can be connected to a remote device is a port, so ports must be formed on all devices with phys if they're connected to anything. Kernel Hackers Manual July 2017 sas_port_delete_phy 9 4.1.27 sas_port_delete_phy remove a phy from a port or wide port void sas_port_delete_phy struct sas_port * port struct sas_phy * phy port port to remove the phy from phy phy to remove This operation is used for tearing down ports again. It must be done to every port or wide port before calling sas_port_delete. Kernel Hackers Manual July 2017 sas_end_device_alloc 9 4.1.27 sas_end_device_alloc allocate an rphy for an end device struct sas_rphy * sas_end_device_alloc struct sas_port * parent parent which port Allocates an SAS remote PHY structure, connected to parent. SAS PHY allocated or NULL if the allocation failed. Kernel Hackers Manual July 2017 sas_expander_alloc 9 4.1.27 sas_expander_alloc allocate an rphy for an end device struct sas_rphy * sas_expander_alloc struct sas_port * parent enum sas_device_type type parent which port type SAS_EDGE_EXPANDER_DEVICE or SAS_FANOUT_EXPANDER_DEVICE Allocates an SAS remote PHY structure, connected to parent. SAS PHY allocated or NULL if the allocation failed. Kernel Hackers Manual July 2017 sas_rphy_add 9 4.1.27 sas_rphy_add add a SAS remote PHY to the device hierarchy int sas_rphy_add struct sas_rphy * rphy rphy The remote PHY to be added Publishes a SAS remote PHY to the rest of the system. Kernel Hackers Manual July 2017 sas_rphy_free 9 4.1.27 sas_rphy_free free a SAS remote PHY void sas_rphy_free struct sas_rphy * rphy rphy SAS remote PHY to free Frees the specified SAS remote PHY. This function must only be called on a remote PHY that has not successfully been added using sas_rphy_add (or has been sas_rphy_remove'd) Kernel Hackers Manual July 2017 sas_rphy_delete 9 4.1.27 sas_rphy_delete remove and free SAS remote PHY void sas_rphy_delete struct sas_rphy * rphy rphy SAS remote PHY to remove and free Removes the specified SAS remote PHY and frees it. Kernel Hackers Manual July 2017 sas_rphy_unlink 9 4.1.27 sas_rphy_unlink unlink SAS remote PHY void sas_rphy_unlink struct sas_rphy * rphy rphy SAS remote phy to unlink from its parent port Removes port reference to an rphy Kernel Hackers Manual July 2017 sas_rphy_remove 9 4.1.27 sas_rphy_remove remove SAS remote PHY void sas_rphy_remove struct sas_rphy * rphy rphy SAS remote phy to remove Removes the specified SAS remote PHY. Kernel Hackers Manual July 2017 scsi_is_sas_rphy 9 4.1.27 scsi_is_sas_rphy check if a struct device represents a SAS remote PHY int scsi_is_sas_rphy const struct device * dev dev device to check 1 if the device represents a SAS remote PHY, 0 else Kernel Hackers Manual July 2017 sas_attach_transport 9 4.1.27 sas_attach_transport instantiate SAS transport template struct scsi_transport_template * sas_attach_transport struct sas_function_template * ft ft SAS transport class function template Kernel Hackers Manual July 2017 sas_release_transport 9 4.1.27 sas_release_transport release SAS transport template instance void sas_release_transport struct scsi_transport_template * t t transport template instance The SATA transport is handled by libata, which has its own book of documentation in this directory. The file drivers/scsi/scsi_transport_spi.c defines transport attributes for traditional (fast/wide/ultra) SCSI busses. Kernel Hackers Manual July 2017 spi_schedule_dv_device 9 4.1.27 spi_schedule_dv_device schedule domain validation to occur on the device void spi_schedule_dv_device struct scsi_device * sdev sdev The device to validate Identical to spi_dv_device above, except that the DV will be scheduled to occur in a workqueue later. All memory allocations are atomic, so may be called from any context including those holding SCSI locks. Kernel Hackers Manual July 2017 spi_display_xfer_agreement 9 4.1.27 spi_display_xfer_agreement Print the current target transfer agreement void spi_display_xfer_agreement struct scsi_target * starget starget The target for which to display the agreement Each SPI port is required to maintain a transfer agreement for each other port on the bus. This function prints a one-line summary of the current agreement; more detailed information is available in sysfs. Kernel Hackers Manual July 2017 spi_populate_tag_msg 9 4.1.27 spi_populate_tag_msg place a tag message in a buffer int spi_populate_tag_msg unsigned char * msg struct scsi_cmnd * cmd msg pointer to the area to place the tag cmd pointer to the scsi command for the tag designed to create the correct type of tag message for the particular request. Returns the size of the tag message. May return 0 if TCQ is disabled for this device. The file drivers/scsi/scsi_transport_srp.c defines transport attributes for SCSI over Remote Direct Memory Access. Kernel Hackers Manual July 2017 srp_tmo_valid 9 4.1.27 srp_tmo_valid check timeout combination validity int srp_tmo_valid int reconnect_delay int fast_io_fail_tmo int dev_loss_tmo reconnect_delay Reconnect delay in seconds. fast_io_fail_tmo Fast I/O fail timeout in seconds. dev_loss_tmo Device loss timeout in seconds. The combination of the timeout parameters must be such that SCSI commands are finished in a reasonable time. Hence do not allow the fast I/O fail timeout to exceed SCSI_DEVICE_BLOCK_MAX_TIMEOUT nor allow dev_loss_tmo to exceed that limit if failing I/O fast has been disabled. Furthermore, these parameters must be such that multipath can detect failed paths timely. Hence do not allow all three parameters to be disabled simultaneously. Kernel Hackers Manual July 2017 srp_start_tl_fail_timers 9 4.1.27 srp_start_tl_fail_timers start the transport layer failure timers void srp_start_tl_fail_timers struct srp_rport * rport rport SRP target port. Start the transport layer fast I/O failure and device loss timers. Do not modify a timer that was already started. Kernel Hackers Manual July 2017 srp_reconnect_rport 9 4.1.27 srp_reconnect_rport reconnect to an SRP target port int srp_reconnect_rport struct srp_rport * rport rport SRP target port. Blocks SCSI command queueing before invoking reconnect such that queuecommand won't be invoked concurrently with reconnect from outside the SCSI EH. This is important since a reconnect implementation may reallocate resources needed by queuecommand. - This function neither waits until outstanding requests have finished nor tries to abort these. It is the responsibility of the reconnect function to finish outstanding commands before reconnecting to the target port. - It is the responsibility of the caller to ensure that the resources reallocated by the reconnect function won't be used while this function is in progress. One possible strategy is to invoke this function from the context of the SCSI EH thread only. Another possible strategy is to lock the rport mutex inside each SCSI LLD callback that can be invoked by the SCSI EH (the scsi_host_template.eh_*() functions and also the scsi_host_template.queuecommand function). Kernel Hackers Manual July 2017 srp_rport_get 9 4.1.27 srp_rport_get increment rport reference count void srp_rport_get struct srp_rport * rport rport SRP target port. Kernel Hackers Manual July 2017 srp_rport_put 9 4.1.27 srp_rport_put decrement rport reference count void srp_rport_put struct srp_rport * rport rport SRP target port. Kernel Hackers Manual July 2017 srp_rport_add 9 4.1.27 srp_rport_add add a SRP remote port to the device hierarchy struct srp_rport * srp_rport_add struct Scsi_Host * shost struct srp_rport_identifiers * ids shost scsi host the remote port is connected to. ids The port id for the remote port. Publishes a port to the rest of the system. Kernel Hackers Manual July 2017 srp_rport_del 9 4.1.27 srp_rport_del remove a SRP remote port void srp_rport_del struct srp_rport * rport rport SRP remote port to remove Removes the specified SRP remote port. Kernel Hackers Manual July 2017 srp_remove_host 9 4.1.27 srp_remove_host tear down a Scsi_Host's SRP data structures void srp_remove_host struct Scsi_Host * shost shost Scsi Host that is torn down Removes all SRP remote ports for a given Scsi_Host. Must be called just before scsi_remove_host for SRP HBAs. Kernel Hackers Manual July 2017 srp_stop_rport_timers 9 4.1.27 srp_stop_rport_timers stop the transport layer recovery timers void srp_stop_rport_timers struct srp_rport * rport rport SRP remote port for which to stop the timers. Must be called after srp_remove_host and scsi_remove_host. The caller must hold a reference on the rport (rport->dev) and on the SCSI host (rport->dev.parent). Kernel Hackers Manual July 2017 srp_attach_transport 9 4.1.27 srp_attach_transport instantiate SRP transport template struct scsi_transport_template * srp_attach_transport struct srp_function_template * ft ft SRP transport class function template Kernel Hackers Manual July 2017 srp_release_transport 9 4.1.27 srp_release_transport release SRP transport template instance void srp_release_transport struct scsi_transport_template * t t transport template instance Many modern device controllers use the SCSI command set as a protocol to communicate with their devices through many different types of physical connections. In SCSI language a bus capable of carrying SCSI commands is called a "transport", and a controller connecting to such a bus is called a "host bus adapter" (HBA). The file drivers/scsi/scsi_debug.c simulates a host adapter with a variable number of disks (or disk like devices) attached, sharing a common amount of RAM. Does a lot of checking to make sure that we are not getting blocks mixed up, and panics the kernel if anything out of the ordinary is seen. To be more realistic, the simulated devices have the transport attributes of SAS disks. For documentation see http://sg.danny.cz/sg/sdebug26.html Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports, netlink...