Skip to content

L
linux
Commit eb44820c authored by Rob Landley's avatar Rob Landley Committed by James Bottomley
Browse files
Options

[SCSI] Add Documentation and integrate into docbook build 

Add Documentation/DocBook/scsi_midlayer.tmpl, add to Makefile, and update
lots of kerneldoc comments in drivers/scsi/*.

Updated with comments from Stefan Richter, Stephen M. Cameron,
 James Bottomley and Randy Dunlap.
Signed-off-by: default avatarRob Landley <rob@landley.net>
Signed-off-by: default avatarJames Bottomley <James.Bottomley@HansenPartnership.com>
parent 3f489858
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 821 additions and 289 deletions
Documentation/DocBook/Makefile
View file @ eb44820c
......@@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
procfs-guide.xml writing_usb_driver.xml \
kernel-api.xml filesystems.xml lsm.xml usb.xml \
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
genericirq.xml s390-drivers.xml uio-howto.xml
genericirq.xml s390-drivers.xml uio-howto.xml scsi_midlayer.xml
###
# The build process is as follows (targets):
......
Documentation/DocBook/scsi_midlayer.tmpl 0 → 100644
View file @ eb44820c
This diff is collapsed.
drivers/scsi/constants.c
View file @ eb44820c
......@@ -362,7 +362,6 @@ void scsi_print_command(struct scsi_cmnd *cmd)
EXPORT_SYMBOL(scsi_print_command);
/**
*
* scsi_print_status - print scsi status description
* @scsi_status: scsi status value
*
......
drivers/scsi/hosts.c
View file @ eb44820c
......@@ -54,8 +54,7 @@ static struct class shost_class = {
};
/**
* scsi_host_set_state - Take the given host through the host
* state model.
* scsi_host_set_state - Take the given host through the host state model.
* @shost: scsi host to change the state of.
* @state: state to change to.
*
......@@ -431,7 +430,6 @@ EXPORT_SYMBOL(scsi_unregister);
/**
* scsi_host_lookup - get a reference to a Scsi_Host by host no
*
* @hostnum: host number to locate
*
* Return value:
......
drivers/scsi/scsi.c
View file @ eb44820c
This diff is collapsed.
drivers/scsi/scsi_devinfo.c
View file @ eb44820c
......@@ -276,11 +276,12 @@ static void scsi_strcpy_devinfo(char *name, char *to, size_t to_length,
}
/**
* scsi_dev_info_list_add: add one dev_info list entry.
* scsi_dev_info_list_add - add one dev_info list entry.
* @compatible: if true, null terminate short strings. Otherwise space pad.
* @vendor: vendor string
* @model: model (product) string
* @strflags: integer string
* @flag: if strflags NULL, use this flag value
* @flags: if strflags NULL, use this flag value
*
* Description:
* Create and add one dev_info entry for @vendor, @model, @strflags or
......@@ -322,8 +323,7 @@ static int scsi_dev_info_list_add(int compatible, char *vendor, char *model,
}
/**
* scsi_dev_info_list_add_str: parse dev_list and add to the
* scsi_dev_info_list.
* scsi_dev_info_list_add_str - parse dev_list and add to the scsi_dev_info_list.
* @dev_list: string of device flags to add
*
* Description:
......@@ -374,15 +374,15 @@ static int scsi_dev_info_list_add_str(char *dev_list)
}
/**
* get_device_flags - get device specific flags from the dynamic device
* list. Called during scan time.
* get_device_flags - get device specific flags from the dynamic device list.
* @sdev: &scsi_device to get flags for
* @vendor: vendor name
* @model: model name
*
* Description:
* Search the scsi_dev_info_list for an entry matching @vendor and
* @model, if found, return the matching flags value, else return
* the host or global default settings.
* the host or global default settings. Called during scan time.
**/
int scsi_get_device_flags(struct scsi_device *sdev,
const unsigned char *vendor,
......@@ -483,13 +483,11 @@ static int proc_scsi_devinfo_read(char *buffer, char **start,
}
/*
* proc_scsi_dev_info_write: allow additions to the scsi_dev_info_list via
* /proc.
* proc_scsi_dev_info_write - allow additions to scsi_dev_info_list via /proc.
*
* Use: echo "vendor:model:flag" > /proc/scsi/device_info
*
* To add a black/white list entry for vendor and model with an integer
* value of flag to the scsi device info list.
* Description: Adds a black/white list entry for vendor and model with an
* integer value of flag to the scsi device info list.
* To use, echo "vendor:model:flag" > /proc/scsi/device_info
*/
static int proc_scsi_devinfo_write(struct file *file, const char __user *buf,
unsigned long length, void *data)
......@@ -532,8 +530,7 @@ MODULE_PARM_DESC(default_dev_flags,
"scsi default device flag integer value");
/**
* scsi_dev_info_list_delete: called from scsi.c:exit_scsi to remove
* the scsi_dev_info_list.
* scsi_dev_info_list_delete - called from scsi.c:exit_scsi to remove the scsi_dev_info_list.
**/
void scsi_exit_devinfo(void)
{
......@@ -552,13 +549,12 @@ void scsi_exit_devinfo(void)
}
/**
* scsi_dev_list_init: set up the dynamic device list.
* @dev_list: string of device flags to add
* scsi_dev_list_init - set up the dynamic device list.
*
* Description:
* Add command line @dev_list entries, then add
* Add command line entries from scsi_dev_flags, then add
* scsi_static_device_list entries to the scsi device info list.
**/
*/
int __init scsi_init_devinfo(void)
{
#ifdef CONFIG_SCSI_PROC_FS
......
drivers/scsi/scsi_error.c
View file @ eb44820c
......@@ -779,7 +779,7 @@ static int scsi_request_sense(struct scsi_cmnd *scmd)
* Notes:
* 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
* 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.
**/
......@@ -794,7 +794,7 @@ EXPORT_SYMBOL(scsi_eh_finish_cmd);
/**
* scsi_eh_get_sense - Get device sense data.
* @work_q: Queue of commands to process.
* @done_q: Queue of proccessed commands..
* @done_q: Queue of processed commands.
*
* Description:
* See if we need to request sense information. if so, then get it
......@@ -802,7 +802,7 @@ EXPORT_SYMBOL(scsi_eh_finish_cmd);
*
* Notes:
* This has the unfortunate side effect that if a shost adapter does
* not automatically request sense information, that we end up shutting
* not automatically request sense information, we end up shutting
* it down before we request it.
*
* All drivers should request sense information internally these days,
......@@ -858,7 +858,7 @@ EXPORT_SYMBOL_GPL(scsi_eh_get_sense);
/**
* scsi_eh_tur - Send TUR to device.
* @scmd: Scsi cmd to send TUR
* @scmd: &scsi_cmnd to send TUR
*
* Return value:
* 0 - Device is ready. 1 - Device NOT ready.
......@@ -887,14 +887,14 @@ static int scsi_eh_tur(struct scsi_cmnd *scmd)
}
/**
* scsi_eh_abort_cmds - abort canceled commands.
* @shost: scsi host being recovered.
* @eh_done_q: list_head for processed commands.
* scsi_eh_abort_cmds - abort pending commands.
* @work_q: &list_head for pending commands.
* @done_q: &list_head for processed commands.
*
* Decription:
* Try and see whether or not it makes sense to try and abort the
* running command. this only works out to be the case if we have one
* command that has timed out. if the command simply failed, it makes
* running command. This only works out to be the case if we have one
* command that has timed out. If the command simply failed, it makes
* no sense to try and abort the command, since as far as the shost
* adapter is concerned, it isn't running.
**/
......@@ -931,7 +931,7 @@ static int scsi_eh_abort_cmds(struct list_head *work_q,
/**
* scsi_eh_try_stu - Send START_UNIT to device.
* @scmd: Scsi cmd to send START_UNIT
* @scmd: &scsi_cmnd to send START_UNIT
*
* Return value:
* 0 - Device is ready. 1 - Device NOT ready.
......@@ -956,8 +956,9 @@ static int scsi_eh_try_stu(struct scsi_cmnd *scmd)
/**
* scsi_eh_stu - send START_UNIT if needed
* @shost: scsi host being recovered.
* @eh_done_q: list_head for processed commands.
* @shost: &scsi host being recovered.
* @work_q: &list_head for pending commands.
* @done_q: &list_head for processed commands.
*
* Notes:
* If commands are failing due to not ready, initializing command required,
......@@ -1008,10 +1009,11 @@ static int scsi_eh_stu(struct Scsi_Host *shost,
/**
* scsi_eh_bus_device_reset - send bdr if needed
* @shost: scsi host being recovered.
* @eh_done_q: list_head for processed commands.
* @work_q: &list_head for pending commands.
* @done_q: &list_head for processed commands.
*
* Notes:
* Try a bus device reset. still, look to see whether we have multiple
* Try a bus device reset. Still, look to see whether we have multiple
* devices that are jammed or not - if we have multiple devices, it
* makes no sense to try bus_device_reset - we really would need to try
* a bus_reset instead.
......@@ -1063,8 +1065,9 @@ static int scsi_eh_bus_device_reset(struct Scsi_Host *shost,
/**
* scsi_eh_bus_reset - send a bus reset
* @shost: scsi host being recovered.
* @eh_done_q: list_head for processed commands.
* @shost: &scsi host being recovered.
* @work_q: &list_head for pending commands.
* @done_q: &list_head for processed commands.
**/
static int scsi_eh_bus_reset(struct Scsi_Host *shost,
struct list_head *work_q,
......@@ -1440,7 +1443,8 @@ static void scsi_restart_operations(struct Scsi_Host *shost)
/**
* scsi_eh_ready_devs - check device ready state and recover if not.
* @shost: host to be recovered.
* @eh_done_q: list_head for processed commands.
* @work_q: &list_head for pending commands.
* @done_q: &list_head for processed commands.
*
**/
void scsi_eh_ready_devs(struct Scsi_Host *shost,
......@@ -1824,9 +1828,7 @@ int scsi_command_normalize_sense(struct scsi_cmnd *cmd,
EXPORT_SYMBOL(scsi_command_normalize_sense);
/**
* scsi_sense_desc_find - search for a given descriptor type in
* descriptor sense data format.
*
* scsi_sense_desc_find - search for a given descriptor type in descriptor sense data format.
* @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
......@@ -1865,9 +1867,7 @@ const u8 * scsi_sense_desc_find(const u8 * sense_buffer, int sb_len,
EXPORT_SYMBOL(scsi_sense_desc_find);
/**
* scsi_get_sense_info_fld - attempts to get information field from
* sense data (either fixed or descriptor format)
*
* scsi_get_sense_info_fld - get information field from sense data (either fixed or descriptor format)
* @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
......
drivers/scsi/scsi_ioctl.c
View file @ eb44820c
......@@ -174,10 +174,15 @@ static int scsi_ioctl_get_pci(struct scsi_device *sdev, void __user *arg)
}
/*
* 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 scsi_devices[] element, a structure.
/**
* scsi_ioctl - Dispatch ioctl to scsi device
* @sdev: scsi device receiving ioctl
* @cmd: which ioctl is it
* @arg: data associated with ioctl
*
* Description: 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.
*/
int scsi_ioctl(struct scsi_device *sdev, int cmd, void __user *arg)
{
......@@ -264,9 +269,12 @@ int scsi_ioctl(struct scsi_device *sdev, int cmd, void __user *arg)
}
EXPORT_SYMBOL(scsi_ioctl);
/*
* the scsi_nonblock_ioctl() function is designed for ioctls which may
* be executed even if the device is in recovery.
/**
* scsi_nonblock_ioctl() - Handle SG_SCSI_RESET
* @sdev: scsi device receiving ioctl
* @cmd: Must be SC_SCSI_RESET
* @arg: pointer to int containing SG_SCSI_RESET_{DEVICE,BUS,HOST}
* @filp: either NULL or a &struct file which must have the O_NONBLOCK flag.
*/
int scsi_nonblockable_ioctl(struct scsi_device *sdev, int cmd,
void __user *arg, struct file *filp)
......@@ -276,7 +284,7 @@ int scsi_nonblockable_ioctl(struct scsi_device *sdev, int cmd,
/* The first set of iocts may be executed even if we're doing
* error processing, as long as the device was opened
* non-blocking */
if (filp && filp->f_flags & O_NONBLOCK) {
if (filp && (filp->f_flags & O_NONBLOCK)) {
if (scsi_host_in_recovery(sdev->host))
return -ENODEV;
} else if (!scsi_block_when_processing_errors(sdev))
......
drivers/scsi/scsi_lib.c
View file @ eb44820c
......@@ -175,7 +175,7 @@ int scsi_queue_insert(struct scsi_cmnd *cmd, int reason)
*
* returns the req->errors value which is the scsi_cmnd result
* field.
**/
*/
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, int flags)
......@@ -274,7 +274,7 @@ static void scsi_bi_endio(struct bio *bio, int error)
/**
* scsi_req_map_sg - map a scatterlist into a request
* @rq: request to fill
* @sg: scatterlist
* @sgl: scatterlist
* @nsegs: number of elements
* @bufflen: len of buffer
* @gfp: memory allocation flags
......@@ -365,14 +365,16 @@ static int scsi_req_map_sg(struct request *rq, struct scatterlist *sgl,
* @sdev: scsi device
* @cmd: scsi command
* @cmd_len: length of scsi cdb
* @data_direction: data direction
* @data_direction: DMA_TO_DEVICE, DMA_FROM_DEVICE, or DMA_NONE
* @buffer: data buffer (this can be a kernel buffer or scatterlist)
* @bufflen: len of buffer
* @use_sg: if buffer is a scatterlist this is the number of elements
* @timeout: request timeout in seconds
* @retries: number of times to retry request
* @flags: or into request flags
**/
* @privdata: data passed to done()
* @done: callback function when done
* @gfp: memory allocation flags
*/
int scsi_execute_async(struct scsi_device *sdev, const unsigned char *cmd,
int cmd_len, int data_direction, void *buffer, unsigned bufflen,
int use_sg, int timeout, int retries, void *privdata,
......@@ -1804,7 +1806,7 @@ void scsi_exit_queue(void)
* @timeout: command timeout
* @retries: number of retries before failing
* @data: returns a structure abstracting the mode header data
* @sense: place to put sense data (or NULL if no sense to be collected).
* @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
......@@ -1871,8 +1873,7 @@ scsi_mode_select(struct scsi_device *sdev, int pf, int sp, int modepage,
EXPORT_SYMBOL_GPL(scsi_mode_select);
/**
* scsi_mode_sense - issue a mode sense, falling back from 10 to
* six bytes if necessary.
* scsi_mode_sense - issue a mode sense, falling back from 10 to six bytes if necessary.
* @sdev: SCSI device to be queried
* @dbd: set if mode sense will allow block descriptors to be returned
* @modepage: mode page being requested
......@@ -1881,13 +1882,13 @@ EXPORT_SYMBOL_GPL(scsi_mode_select);
* @timeout: command timeout
* @retries: number of retries before failing
* @data: returns a structure abstracting the mode header data
* @sense: place to put sense data (or NULL if no sense to be collected).
* @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.
**/
*/
int
scsi_mode_sense(struct scsi_device *sdev, int dbd, int modepage,
unsigned char *buffer, int len, int timeout, int retries,
......@@ -2007,14 +2008,13 @@ scsi_test_unit_ready(struct scsi_device *sdev, int timeout, int retries)
EXPORT_SYMBOL(scsi_test_unit_ready);
/**
* scsi_device_set_state - Take the given device through the device
* state model.
* scsi_device_set_state - Take the given device through the device state model.
* @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.
**/
*/
int
scsi_device_set_state(struct scsi_device *sdev, enum scsi_device_state state)
{
......@@ -2264,7 +2264,7 @@ EXPORT_SYMBOL_GPL(sdev_evt_send_simple);
* Must be called with user context, may sleep.
*
* Returns zero if unsuccessful or an error if not.
**/
*/
int
scsi_device_quiesce(struct scsi_device *sdev)
{
......@@ -2289,7 +2289,7 @@ EXPORT_SYMBOL(scsi_device_quiesce);
* queues.
*
* Must be called with user context, may sleep.
**/
*/
void
scsi_device_resume(struct scsi_device *sdev)
{
......@@ -2326,8 +2326,7 @@ scsi_target_resume(struct scsi_target *starget)
EXPORT_SYMBOL(scsi_target_resume);
/**
* scsi_internal_device_block - internal function to put a device
* temporarily into the SDEV_BLOCK state
* scsi_internal_device_block - internal function to put a device temporarily into the SDEV_BLOCK state
* @sdev: device to block
*
* Block request made by scsi lld's to temporarily stop all
......@@ -2342,7 +2341,7 @@ EXPORT_SYMBOL(scsi_target_resume);
* state, all commands are deferred until the scsi lld reenables
* the device with scsi_device_unblock or device_block_tmo fires.
* This routine assumes the host_lock is held on entry.
**/
*/
int
scsi_internal_device_block(struct scsi_device *sdev)
{
......@@ -2382,7 +2381,7 @@ EXPORT_SYMBOL_GPL(scsi_internal_device_block);
* (which must be a legal transition) allowing the midlayer to
* goose the queue for this device. This routine assumes the
* host_lock is held upon entry.
**/
*/
int
scsi_internal_device_unblock(struct scsi_device *sdev)
{
......@@ -2460,7 +2459,7 @@ EXPORT_SYMBOL_GPL(scsi_target_unblock);
/**
* scsi_kmap_atomic_sg - find and atomically map an sg-elemnt
* @sg: scatter-gather list
* @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
......@@ -2509,8 +2508,7 @@ void *scsi_kmap_atomic_sg(struct scatterlist *sgl, int sg_count,
EXPORT_SYMBOL(scsi_kmap_atomic_sg);
/**
* scsi_kunmap_atomic_sg - atomically unmap a virtual address, previously
* mapped with scsi_kmap_atomic_sg
* scsi_kunmap_atomic_sg - atomically unmap a virtual address, previously mapped with scsi_kmap_atomic_sg
* @virt: virtual address to be unmapped
*/
void scsi_kunmap_atomic_sg(void *virt)
......
drivers/scsi/scsi_netlink.c
View file @ eb44820c
......@@ -32,11 +32,12 @@ EXPORT_SYMBOL_GPL(scsi_nl_sock);
/**
* scsi_nl_rcv_msg -
* Receive message handler. Extracts message from a receive buffer.
* scsi_nl_rcv_msg - Receive message handler.
* @skb: socket receive buffer
*
* Description: Extracts message from a receive buffer.
* Validates message header and calls appropriate transport message handler
*
* @skb: socket receive buffer
*
**/
static void
......@@ -99,9 +100,7 @@ scsi_nl_rcv_msg(struct sk_buff *skb)
/**
* scsi_nl_rcv_event -
* Event handler for a netlink socket.
*
* scsi_nl_rcv_event - Event handler for a netlink socket.
* @this: event notifier block
* @event: event type
* @ptr: event payload
......@@ -129,9 +128,7 @@ static struct notifier_block scsi_netlink_notifier = {
/**
* scsi_netlink_init -
* Called by SCSI subsystem to intialize the SCSI transport netlink
* interface
* scsi_netlink_init - Called by SCSI subsystem to intialize the SCSI transport netlink interface
*
**/
void
......@@ -160,9 +157,7 @@ scsi_netlink_init(void)
/**
* scsi_netlink_exit -
* Called by SCSI subsystem to disable the SCSI transport netlink
* interface
* scsi_netlink_exit - Called by SCSI subsystem to disable the SCSI transport netlink interface
*
**/
void
......
drivers/scsi/scsi_proc.c
View file @ eb44820c
......@@ -45,6 +45,16 @@ static struct proc_dir_entry *proc_scsi;
/* Protect sht->present and sht->proc_dir */
static DEFINE_MUTEX(global_host_template_mutex);
/**
* proc_scsi_read - handle read from /proc by calling host's proc_info() command
* @buffer: passed to proc_info
* @start: passed to proc_info
* @offset: passed to proc_info
* @length: passed to proc_info
* @eof: returns whether length read was less than requested
* @data: pointer to a &struct Scsi_Host
*/
static int proc_scsi_read(char *buffer, char **start, off_t offset,
int length, int *eof, void *data)
{
......@@ -57,6 +67,13 @@ static int proc_scsi_read(char *buffer, char **start, off_t offset,
return n;
}
/**
* proc_scsi_write_proc - Handle write to /proc by calling host's proc_info()
* @file: not used
* @buf: source of data to write.
* @count: number of bytes (at most PROC_BLOCK_SIZE) to write.
* @data: pointer to &struct Scsi_Host
*/
static int proc_scsi_write_proc(struct file *file, const char __user *buf,
unsigned long count, void *data)
{
......@@ -80,6 +97,13 @@ static int proc_scsi_write_proc(struct file *file, const char __user *buf,
return ret;
}
/**
* scsi_proc_hostdir_add - Create directory in /proc for a scsi host
* @sht: owner of this directory
*
* Sets sht->proc_dir to the new directory.
*/
void scsi_proc_hostdir_add(struct scsi_host_template *sht)
{
if (!sht->proc_info)
......@@ -97,6 +121,10 @@ void scsi_proc_hostdir_add(struct scsi_host_template *sht)
mutex_unlock(&global_host_template_mutex);
}
/**
* scsi_proc_hostdir_rm - remove directory in /proc for a scsi host
* @sht: owner of directory
*/
void scsi_proc_hostdir_rm(struct scsi_host_template *sht)
{
if (!sht->proc_info)
......@@ -110,6 +138,11 @@ void scsi_proc_hostdir_rm(struct scsi_host_template *sht)
mutex_unlock(&global_host_template_mutex);
}
/**
* scsi_proc_host_add - Add entry for this host to appropriate /proc dir
* @shost: host to add
*/
void scsi_proc_host_add(struct Scsi_Host *shost)
{
struct scsi_host_template *sht = shost->hostt;
......@@ -133,6 +166,10 @@ void scsi_proc_host_add(struct Scsi_Host *shost)
p->owner = sht->module;
}
/**
* scsi_proc_host_rm - remove this host's entry from /proc
* @shost: which host
*/
void scsi_proc_host_rm(struct Scsi_Host *shost)
{
char name[10];
......@@ -143,7 +180,14 @@ void scsi_proc_host_rm(struct Scsi_Host *shost)
sprintf(name,"%d", shost->host_no);
remove_proc_entry(name, shost->hostt->proc_dir);
}
/**
* proc_print_scsidevice - return data about this host
* @dev: A scsi device
* @data: &struct seq_file to output to.
*
* Description: prints Host, Channel, Id, Lun, Vendor, Model, Rev, Type,
* and revision.
*/
static int proc_print_scsidevice(struct device *dev, void *data)
{
struct scsi_device *sdev = to_scsi_device(dev);
......@@ -189,6 +233,21 @@ static int proc_print_scsidevice(struct device *dev, void *data)
return 0;
}
/**
* scsi_add_single_device - Respond to user request to probe for/add device
* @host: user-supplied decimal integer
* @channel: user-supplied decimal integer
* @id: user-supplied decimal integer
* @lun: user-supplied decimal integer
*
* Description: 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()
*
* Note: this seems to be aimed exclusively at SCSI parallel busses.
*/
static int scsi_add_single_device(uint host, uint channel, uint id, uint lun)
{
struct Scsi_Host *shost;
......@@ -206,6 +265,16 @@ static int scsi_add_single_device(uint host, uint channel, uint id, uint lun)
return error;
}
/**
* scsi_remove_single_device - Respond to user request to remove a device
* @host: user-supplied decimal integer
* @channel: user-supplied decimal integer
* @id: user-supplied decimal integer
* @lun: user-supplied decimal integer
*
* Description: called by writing "scsi remove-single-device" to
* /proc/scsi/scsi. Does a scsi_device_lookup() and scsi_remove_device()
*/
static int scsi_remove_single_device(uint host, uint channel, uint id, uint lun)
{
struct scsi_device *sdev;
......@@ -226,6 +295,25 @@ static int scsi_remove_single_device(uint host, uint channel, uint id, uint lun)
return error;
}
/**
* proc_scsi_write - handle writes to /proc/scsi/scsi
* @file: not used
* @buf: buffer to write
* @length: length of buf, at most PAGE_SIZE
* @ppos: not used
*
* Description: 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.
*
* Note: 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.
*/
static ssize_t proc_scsi_write(struct file *file, const char __user *buf,
size_t length, loff_t *ppos)
{
......@@ -291,6 +379,11 @@ static ssize_t proc_scsi_write(struct file *file, const char __user *buf,
return err;
}
/**
* proc_scsi_show - show contents of /proc/scsi/scsi (attached devices)
* @s: output goes here
* @p: not used
*/
static int proc_scsi_show(struct seq_file *s, void *p)
{
seq_printf(s, "Attached devices:\n");
......@@ -298,10 +391,17 @@ static int proc_scsi_show(struct seq_file *s, void *p)
return 0;
}
/**
* proc_scsi_open - glue function
* @inode: not used
* @file: passed to single_open()
*
* Associates proc_scsi_show with this file
*/
static int proc_scsi_open(struct inode *inode, struct file *file)
{
/*
* We don't really needs this for the write case but it doesn't
* We don't really need this for the write case but it doesn't
* harm either.
*/
return single_open(file, proc_scsi_show, NULL);
......@@ -315,6 +415,9 @@ static const struct file_operations proc_scsi_operations = {
.release = single_release,
};
/**
* scsi_init_procfs - create scsi and scsi/scsi in procfs
*/
int __init scsi_init_procfs(void)
{
struct proc_dir_entry *pde;
......@@ -336,6 +439,9 @@ int __init scsi_init_procfs(void)
return -ENOMEM;
}
/**
* scsi_exit_procfs - Remove scsi/scsi and scsi from procfs
*/
void scsi_exit_procfs(void)
{
remove_proc_entry("scsi/scsi", NULL);
......
drivers/scsi/scsi_scan.c
View file @ eb44820c
......@@ -221,6 +221,9 @@ static void scsi_unlock_floptical(struct scsi_device *sdev,
/**
* scsi_alloc_sdev - allocate and setup a scsi_Device
* @starget: which target to allocate a &scsi_device for
* @lun: which lun
* @hostdata: usually NULL and set by ->slave_alloc instead
*
* Description:
* Allocate, initialize for io, and return a pointer to a scsi_Device.
......@@ -472,7 +475,6 @@ static void scsi_target_reap_usercontext(struct work_struct *work)
/**
* scsi_target_reap - check to see if target is in use and destroy if not
*
* @starget: target to be checked
*
* This is used after removing a LUN or doing a last put of the target
......@@ -928,8 +930,7 @@ static inline void scsi_destroy_sdev(struct scsi_device *sdev)
#ifdef CONFIG_SCSI_LOGGING
/**
* scsi_inq_str - print INQUIRY data from min to max index,
* strip trailing whitespace
* scsi_inq_str - print INQUIRY data from min to max index, strip trailing whitespace
* @buf: Output buffer with at least end-first+1 bytes of space
* @inq: Inquiry buffer (input)
* @first: Offset of string into inq
......@@ -957,9 +958,10 @@ static unsigned char *scsi_inq_str(unsigned char *buf, unsigned char *inq,
* scsi_probe_and_add_lun - probe a LUN, if a LUN is found add it
* @starget: pointer to target device structure
* @lun: LUN of target device
* @sdevscan: probe the LUN corresponding to this scsi_device
* @sdevnew: store the value of any new scsi_device allocated
* @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()
*
* Description:
* Call scsi_probe_lun, if a LUN with an attached device is found,
......@@ -1110,6 +1112,8 @@ static int scsi_probe_and_add_lun(struct scsi_target *starget,
* scsi_sequential_lun_scan - sequentially scan a SCSI target
* @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()
*
* Description:
* Generally, scan from LUN 1 (LUN 0 is assumed to already have been
......@@ -1220,7 +1224,7 @@ EXPORT_SYMBOL(scsilun_to_int);
/**
* int_to_scsilun: reverts an int into a scsi_lun
* @int: integer to be reverted
* @lun: integer to be reverted
* @scsilun: struct scsi_lun to be set.
*
* Description:
......@@ -1252,18 +1256,22 @@ EXPORT_SYMBOL(int_to_scsilun);
/**
* scsi_report_lun_scan - Scan using SCSI REPORT LUN results
* @sdevscan: scan the host, channel, and id of this scsi_device
* @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
*
* Description:
* If @sdevscan is for a SCSI-3 or up device, send a REPORT LUN
* command, and scan the resulting list of LUNs by calling
* scsi_probe_and_add_lun.
* 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.
*
* Modifies sdevscan->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.
*
* Return:
* 0: scan completed (or no memory, so further scanning is futile)
* 1: no report lun scan, or not configured
* 1: could not scan with REPORT LUN
**/
static int scsi_report_lun_scan(struct scsi_target *starget, int bflags,
int rescan)
......
drivers/scsi/scsi_transport_fc.c
View file @ eb44820c
This diff is collapsed.
drivers/scsi/scsi_transport_iscsi.c
View file @ eb44820c
......@@ -328,9 +328,10 @@ EXPORT_SYMBOL_GPL(iscsi_add_session);
* iscsi_create_session - create iscsi class session
* @shost: scsi host
* @transport: iscsi transport
* @target_id: which target
*
* This can be called from a LLD or iscsi_transport.
**/
*/
struct iscsi_cls_session *
iscsi_create_session(struct Scsi_Host *shost,
struct iscsi_transport *transport,
......@@ -382,7 +383,7 @@ EXPORT_SYMBOL_GPL(iscsi_free_session);
*
* Can be called by a LLD or iscsi_transport. There must not be
* any running connections.
**/
*/
int iscsi_destroy_session(struct iscsi_cls_session *session)
{
iscsi_remove_session(session);
......@@ -418,7 +419,7 @@ static int iscsi_is_conn_dev(const struct device *dev)
* 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.
**/
*/
struct iscsi_cls_conn *
iscsi_create_conn(struct iscsi_cls_session *session, uint32_t cid)
{
......@@ -465,10 +466,10 @@ EXPORT_SYMBOL_GPL(iscsi_create_conn);
/**
* iscsi_destroy_conn - destroy iscsi class connection
* @session: iscsi cls session
* @conn: iscsi cls session
*
* This can be called from a LLD or iscsi_transport.
**/
* This can be called from an LLD or iscsi_transport.
*/
int iscsi_destroy_conn(struct iscsi_cls_conn *conn)
{
transport_unregister_device(&conn->dev);
......@@ -690,7 +691,7 @@ iscsi_if_get_stats(struct iscsi_transport *transport, struct nlmsghdr *nlh)
*
* This is called by HW iscsi LLDs to notify userpsace that its HW has
* removed a session.
**/
*/
int iscsi_if_destroy_session_done(struct iscsi_cls_conn *conn)
{
struct iscsi_internal *priv;
......@@ -751,7 +752,7 @@ EXPORT_SYMBOL_GPL(iscsi_if_destroy_session_done);
*
* This is called by HW iscsi LLDs to notify userpsace that its HW has
* created a session or a existing session is back in the logged in state.
**/
*/
int iscsi_if_create_session_done(struct iscsi_cls_conn *conn)
{
struct iscsi_internal *priv;
......
drivers/scsi/scsi_transport_sas.c
View file @ eb44820c
......@@ -323,7 +323,7 @@ static int do_sas_phy_delete(struct device *dev, void *data)
}
/**
* sas_remove_children -- tear down a devices SAS data structures
* sas_remove_children - tear down a devices SAS data structures
* @dev: device belonging to the sas object
*
* Removes all SAS PHYs and remote PHYs for a given object
......@@ -336,7 +336,7 @@ void sas_remove_children(struct device *dev)
EXPORT_SYMBOL(sas_remove_children);
/**
* sas_remove_host -- tear down a Scsi_Host's SAS data structures
* sas_remove_host - tear down a Scsi_Host's SAS data structures
* @shost: Scsi Host that is torn down
*
* Removes all SAS PHYs and remote PHYs for a given Scsi_Host.
......@@ -577,7 +577,7 @@ static void sas_phy_release(struct device *dev)
}
/**
* sas_phy_alloc -- allocates and initialize a SAS PHY structure
* sas_phy_alloc - allocates and initialize a SAS PHY structure
* @parent: Parent device
* @number: Phy index
*
......@@ -618,7 +618,7 @@ struct sas_phy *sas_phy_alloc(struct device *parent, int number)
EXPORT_SYMBOL(sas_phy_alloc);
/**
* sas_phy_add -- add a SAS PHY to the device hierarchy
* sas_phy_add - add a SAS PHY to the device hierarchy
* @phy: The PHY to be added
*
* Publishes a SAS PHY to the rest of the system.
......@@ -638,7 +638,7 @@ int sas_phy_add(struct sas_phy *phy)
EXPORT_SYMBOL(sas_phy_add);
/**
* sas_phy_free -- free a SAS PHY
* sas_phy_free - free a SAS PHY
* @phy: SAS PHY to free
*
* Frees the specified SAS PHY.
......@@ -655,7 +655,7 @@ void sas_phy_free(struct sas_phy *phy)
EXPORT_SYMBOL(sas_phy_free);
/**
* sas_phy_delete -- remove SAS PHY
* sas_phy_delete - remove SAS PHY
* @phy: SAS PHY to remove
*
* Removes the specified SAS PHY. If the SAS PHY has an
......@@ -677,7 +677,7 @@ sas_phy_delete(struct sas_phy *phy)
EXPORT_SYMBOL(sas_phy_delete);
/**
* scsi_is_sas_phy -- check if a struct device represents a SAS PHY
* scsi_is_sas_phy - check if a struct device represents a SAS PHY
* @dev: device to check
*
* Returns:
......@@ -843,7 +843,6 @@ EXPORT_SYMBOL(sas_port_alloc_num);
/**
* sas_port_add - add a SAS port to the device hierarchy
*
* @port: port to be added
*
* publishes a port to the rest of the system
......@@ -868,7 +867,7 @@ int sas_port_add(struct sas_port *port)
EXPORT_SYMBOL(sas_port_add);
/**
* sas_port_free -- free a SAS PORT
* sas_port_free - free a SAS PORT
* @port: SAS PORT to free
*
* Frees the specified SAS PORT.
......@@ -885,7 +884,7 @@ void sas_port_free(struct sas_port *port)
EXPORT_SYMBOL(sas_port_free);
/**
* sas_port_delete -- remove SAS PORT
* sas_port_delete - remove SAS PORT
* @port: SAS PORT to remove
*
* Removes the specified SAS PORT. If the SAS PORT has an
......@@ -924,7 +923,7 @@ void sas_port_delete(struct sas_port *port)
EXPORT_SYMBOL(sas_port_delete);
/**
* scsi_is_sas_port -- check if a struct device represents a SAS port
* scsi_is_sas_port - check if a struct device represents a SAS port
* @dev: device to check
*
* Returns:
......@@ -1309,6 +1308,7 @@ static void sas_rphy_initialize(struct sas_rphy *rphy)
/**
* sas_end_device_alloc - allocate an rphy for an end device
* @parent: which port
*
* Allocates an SAS remote PHY structure, connected to @parent.
*
......@@ -1345,6 +1345,8 @@ EXPORT_SYMBOL(sas_end_device_alloc);
/**
* sas_expander_alloc - allocate an rphy for an end device
* @parent: which port
* @type: SAS_EDGE_EXPANDER_DEVICE or SAS_FANOUT_EXPANDER_DEVICE
*
* Allocates an SAS remote PHY structure, connected to @parent.
*
......@@ -1383,7 +1385,7 @@ struct sas_rphy *sas_expander_alloc(struct sas_port *parent,
EXPORT_SYMBOL(sas_expander_alloc);
/**
* sas_rphy_add -- add a SAS remote PHY to the device hierarchy
* sas_rphy_add - add a SAS remote PHY to the device hierarchy
* @rphy: The remote PHY to be added
*
* Publishes a SAS remote PHY to the rest of the system.
......@@ -1430,8 +1432,8 @@ int sas_rphy_add(struct sas_rphy *rphy)
EXPORT_SYMBOL(sas_rphy_add);
/**
* sas_rphy_free -- free a SAS remote PHY
* @rphy SAS remote PHY to free
* sas_rphy_free - free a SAS remote PHY
* @rphy: SAS remote PHY to free
*
* Frees the specified SAS remote PHY.
*
......@@ -1459,7 +1461,7 @@ void sas_rphy_free(struct sas_rphy *rphy)
EXPORT_SYMBOL(sas_rphy_free);
/**
* sas_rphy_delete -- remove and free SAS remote PHY
* sas_rphy_delete - remove and free SAS remote PHY
* @rphy: SAS remote PHY to remove and free
*
* Removes the specified SAS remote PHY and frees it.
......@@ -1473,7 +1475,7 @@ sas_rphy_delete(struct sas_rphy *rphy)
EXPORT_SYMBOL(sas_rphy_delete);
/**
* sas_rphy_remove -- remove SAS remote PHY
* sas_rphy_remove - remove SAS remote PHY
* @rphy: SAS remote phy to remove
*
* Removes the specified SAS remote PHY.
......@@ -1504,7 +1506,7 @@ sas_rphy_remove(struct sas_rphy *rphy)
EXPORT_SYMBOL(sas_rphy_remove);
/**
* scsi_is_sas_rphy -- check if a struct device represents a SAS remote PHY
* scsi_is_sas_rphy - check if a struct device represents a SAS remote PHY
* @dev: device to check
*
* Returns:
......@@ -1604,7 +1606,7 @@ static int sas_user_scan(struct Scsi_Host *shost, uint channel,
SETUP_TEMPLATE(expander_attrs, expander_##field, S_IRUGO, 1)
/**
* sas_attach_transport -- instantiate SAS transport template
* sas_attach_transport - instantiate SAS transport template
* @ft: SAS transport class function template
*/
struct scsi_transport_template *
......@@ -1715,7 +1717,7 @@ sas_attach_transport(struct sas_function_template *ft)
EXPORT_SYMBOL(sas_attach_transport);
/**
* sas_release_transport -- release SAS transport template instance
* sas_release_transport - release SAS transport template instance
* @t: transport template instance
*/
void sas_release_transport(struct scsi_transport_template *t)
......
drivers/scsi/scsi_transport_srp.c
View file @ eb44820c
......@@ -242,8 +242,8 @@ struct srp_rport *srp_rport_add(struct Scsi_Host *shost,
EXPORT_SYMBOL_GPL(srp_rport_add);
/**
* srp_rport_del -- remove a SRP remote port
* @port: SRP remote port to remove
* srp_rport_del - remove a SRP remote port
* @rport: SRP remote port to remove
*
* Removes the specified SRP remote port.
*/
......@@ -271,7 +271,7 @@ static int do_srp_rport_del(struct device *dev, void *data)
}
/**
* srp_remove_host -- tear down a Scsi_Host's SRP data structures
* srp_remove_host - tear down a Scsi_Host's SRP data structures
* @shost: Scsi Host that is torn down
*
* Removes all SRP remote ports for a given Scsi_Host.
......@@ -297,7 +297,7 @@ static int srp_it_nexus_response(struct Scsi_Host *shost, u64 nexus, int result)
}
/**
* srp_attach_transport -- instantiate SRP transport template
* srp_attach_transport - instantiate SRP transport template
* @ft: SRP transport class function template
*/
struct scsi_transport_template *
......@@ -337,7 +337,7 @@ srp_attach_transport(struct srp_function_template *ft)
EXPORT_SYMBOL_GPL(srp_attach_transport);
/**
* srp_release_transport -- release SRP transport template instance
* srp_release_transport - release SRP transport template instance
* @t: transport template instance
*/
void srp_release_transport(struct scsi_transport_template *t)
......
drivers/scsi/scsicam.c
View file @ eb44820c
......@@ -24,6 +24,14 @@
static int setsize(unsigned long capacity, unsigned int *cyls, unsigned int *hds,
unsigned int *secs);
/**
* scsi_bios_ptable - Read PC partition table out of first sector of device.
* @dev: from this device
*
* Description: Reads the first sector from the device and returns %0x42 bytes
* starting at offset %0x1be.
* Returns: partition table in kmalloc(GFP_KERNEL) memory, or NULL on error.
*/
unsigned char *scsi_bios_ptable(struct block_device *dev)
{
unsigned char *res = kmalloc(66, GFP_KERNEL);
......@@ -43,15 +51,17 @@ unsigned char *scsi_bios_ptable(struct block_device *dev)
}
EXPORT_SYMBOL(scsi_bios_ptable);
/*
* Function : int scsicam_bios_param (struct block_device *bdev, ector_t capacity, int *ip)
/**
* scsicam_bios_param - Determine geometry of a disk in cylinders/heads/sectors.
* @bdev: which device
* @capacity: size of the disk in sectors
* @ip: return value: ip[0]=heads, ip[1]=sectors, ip[2]=cylinders
*
* Purpose : to determine the BIOS mapping used for a drive in a
* Description : 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().
*
* Returns : -1 on failure, 0 on success.
*
*/
int scsicam_bios_param(struct block_device *bdev, sector_t capacity, int *ip)
......@@ -98,15 +108,18 @@ int scsicam_bios_param(struct block_device *bdev, sector_t capacity, int *ip)
}
EXPORT_SYMBOL(scsicam_bios_param);
/*
* Function : static int scsi_partsize(unsigned char *buf, unsigned long
* capacity,unsigned int *cyls, unsigned int *hds, unsigned int *secs);
/**
* scsi_partsize - Parse cylinders/heads/sectors from PC partition table
* @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
*
* Purpose : to determine the BIOS mapping used to create the partition
* Description: determine the BIOS mapping/geometry used to create the partition
* table, storing the results in *cyls, *hds, and *secs
*
* Returns : -1 on failure, 0 on success.
*
* Returns: -1 on failure, 0 on success.
*/
int scsi_partsize(unsigned char *buf, unsigned long capacity,
......@@ -194,7 +207,7 @@ EXPORT_SYMBOL(scsi_partsize);
*
* WORKING X3T9.2
* DRAFT 792D
*
* see http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf
*
* Revision 6
* 10-MAR-94
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7