scsi: docs: convert scsi_mid_low_api.txt to ReST

Mauro Carvalho Chehab committed 6 years ago

Commit ce5c5d61 parent d4d79345 files · +1337 −1282Browse files

Unified · Split

5 files

Documentation/scsi/index.rst +1 −0
Documentation/scsi/scsi_eh.rst +1 −1
Documentation/scsi/scsi_mid_low_api.rst +1334 −0
Documentation/scsi/scsi_mid_low_api.txt +0 −1280
scripts/documentation-file-ref-check +1 −1

@@ -35,5 +35,6 @@ Linux SCSI Subsystem · 34 unmodified lines
35	35	scsi_eh
36	36	scsi_fc_transport
37	37	scsi-generic
	38	+ scsi_mid_low_api
38	39
39	40	scsi_transport_srp/figures

Documentation/scsi/scsi_eh.rst+1−1

@@ -5,7 +5,7 @@ SCSI EH · 4 unmodified lines
5	5	=======
6	6
7	7	This document describes SCSI midlayer error handling infrastructure.
8		−Please refer to Documentation/scsi/scsi_mid_low_api.txt for more
	8	+Please refer to Documentation/scsi/scsi_mid_low_api.rst for more
9	9	information regarding SCSI midlayer.
10	10
11	11	.. TABLE OF CONTENTS

Documentation/scsi/scsi_mid_low_api.rst+1334−0

@@ -0,0 +1,1334 @@
	1	+.. SPDX-License-Identifier: GPL-2.0
	2	+
	3	+=============================================
	4	+SCSI mid_level - lower_level driver interface
	5	+=============================================
	6	+
	7	+Introduction
	8	+============
	9	+This document outlines the interface between the Linux SCSI mid level and
	10	+SCSI lower level drivers. Lower level drivers (LLDs) are variously called
	11	+host bus adapter (HBA) drivers and host drivers (HD). A "host" in this
	12	+context is a bridge between a computer IO bus (e.g. PCI or ISA) and a
	13	+single SCSI initiator port on a SCSI transport. An "initiator" port
	14	+(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
	15	+to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
	16	+system, but only one per hardware type. Most LLDs can control one or more
	17	+SCSI HBAs. Some HBAs contain multiple hosts.
	18	+
	19	+In some cases the SCSI transport is an external bus that already has
	20	+its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
	21	+SCSI subsystem LLD is a software bridge to the other driver subsystem.
	22	+Examples are the usb-storage driver (found in the drivers/usb/storage
	23	+directory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394
	24	+directory).
	25	+
	26	+For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
	27	+(SPI) controllers based on that company's 7xxx chip series. The aic7xxx
	28	+LLD can be built into the kernel or loaded as a module. There can only be
	29	+one aic7xxx LLD running in a Linux system but it may be controlling many
	30	+HBAs. These HBAs might be either on PCI daughter-boards or built into
	31	+the motherboard (or both). Some aic7xxx based HBAs are dual controllers
	32	+and thus represent two hosts. Like most modern HBAs, each aic7xxx host
	33	+has its own PCI device address. [The one-to-one correspondence between
	34	+a SCSI host and a PCI device is common but not required (e.g. with
	35	+ISA adapters).]
	36	+
	37	+The SCSI mid level isolates an LLD from other layers such as the SCSI
	38	+upper layer drivers and the block layer.
	39	+
	40	+This version of the document roughly matches linux kernel version 2.6.8 .
	41	+
	42	+Documentation
	43	+=============
	44	+There is a SCSI documentation directory within the kernel source tree,
	45	+typically Documentation/scsi . Most documents are in plain
	46	+(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be
	47	+found in that directory. A more recent copy of this document may be found
	48	+at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/.
	49	+Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
	50	+briefly described in scsi.txt which contains a url to a document
	51	+describing the SCSI subsystem in the lk 2.4 series. Two upper level
	52	+drivers have documents in that directory: st.txt (SCSI tape driver) and
	53	+scsi-generic.txt (for the sg driver).
	54	+
	55	+Some documentation (or urls) for LLDs may be found in the C source code
	56	+or in the same directory as the C source code. For example to find a url
	57	+about the USB mass storage driver see the
	58	+/usr/src/linux/drivers/usb/storage directory.
	59	+
	60	+Driver structure
	61	+================
	62	+Traditionally an LLD for the SCSI subsystem has been at least two files in
	63	+the drivers/scsi directory. For example, a driver called "xyz" has a header
	64	+file "xyz.h" and a source file "xyz.c". [Actually there is no good reason
	65	+why this couldn't all be in one file; the header file is superfluous.] Some
	66	+drivers that have been ported to several operating systems have more than
	67	+two files. For example the aic7xxx driver has separate files for generic
	68	+and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
	69	+their own directory under the drivers/scsi directory.
	70	+
	71	+When a new LLD is being added to Linux, the following files (found in the
	72	+drivers/scsi directory) will need some attention: Makefile and Kconfig .
	73	+It is probably best to study how existing LLDs are organized.
	74	+
	75	+As the 2.5 series development kernels evolve into the 2.6 series
	76	+production series, changes are being introduced into this interface. An
	77	+example of this is driver initialization code where there are now 2 models
	78	+available. The older one, similar to what was found in the lk 2.4 series,
	79	+is based on hosts that are detected at HBA driver load time. This will be
	80	+referred to the "passive" initialization model. The newer model allows HBAs
	81	+to be hot plugged (and unplugged) during the lifetime of the LLD and will
	82	+be referred to as the "hotplug" initialization model. The newer model is
	83	+preferred as it can handle both traditional SCSI equipment that is
	84	+permanently connected as well as modern "SCSI" devices (e.g. USB or
	85	+IEEE 1394 connected digital cameras) that are hotplugged. Both
	86	+initialization models are discussed in the following sections.
	87	+
	88	+An LLD interfaces to the SCSI subsystem several ways:
	89	+
	90	+ a) directly invoking functions supplied by the mid level
	91	+ b) passing a set of function pointers to a registration function
	92	+ supplied by the mid level. The mid level will then invoke these
	93	+ functions at some point in the future. The LLD will supply
	94	+ implementations of these functions.
	95	+ c) direct access to instances of well known data structures maintained
	96	+ by the mid level
	97	+
	98	+Those functions in group a) are listed in a section entitled "Mid level
	99	+supplied functions" below.
	100	+
	101	+Those functions in group b) are listed in a section entitled "Interface
	102	+functions" below. Their function pointers are placed in the members of
	103	+"struct scsi_host_template", an instance of which is passed to
	104	+scsi_host_alloc() [#]_. Those interface functions that the LLD does not
	105	+wish to supply should have NULL placed in the corresponding member of
	106	+struct scsi_host_template. Defining an instance of struct
	107	+scsi_host_template at file scope will cause NULL to be placed in function
	108	+pointer members not explicitly initialized.
	109	+
	110	+Those usages in group c) should be handled with care, especially in a
	111	+"hotplug" environment. LLDs should be aware of the lifetime of instances
	112	+that are shared with the mid level and other layers.
	113	+
	114	+All functions defined within an LLD and all data defined at file scope
	115	+should be static. For example the slave_alloc() function in an LLD
	116	+called "xxx" could be defined as
	117	+``static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }``
	118	+
	119	+.. [#] the scsi_host_alloc() function is a replacement for the rather vaguely
	120	+ named scsi_register() function in most situations.
	121	+
	122	+
	123	+Hotplug initialization model
	124	+============================
	125	+In this model an LLD controls when SCSI hosts are introduced and removed
	126	+from the SCSI subsystem. Hosts can be introduced as early as driver
	127	+initialization and removed as late as driver shutdown. Typically a driver
	128	+will respond to a sysfs probe() callback that indicates an HBA has been
	129	+detected. After confirming that the new device is one that the LLD wants
	130	+to control, the LLD will initialize the HBA and then register a new host
	131	+with the SCSI mid level.
	132	+
	133	+During LLD initialization the driver should register itself with the
	134	+appropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus).
	135	+This can probably be done via sysfs. Any driver parameters (especially
	136	+those that are writable after the driver is loaded) could also be
	137	+registered with sysfs at this point. The SCSI mid level first becomes
	138	+aware of an LLD when that LLD registers its first HBA.
	139	+
	140	+At some later time, the LLD becomes aware of an HBA and what follows
	141	+is a typical sequence of calls between the LLD and the mid level.
	142	+This example shows the mid level scanning the newly introduced HBA for 3
	143	+scsi devices of which only the first 2 respond::
	144	+
	145	+ HBA PROBE: assume 2 SCSI devices found in scan
	146	+ LLD mid level LLD
	147	+ ===-------------------=========--------------------===------
	148	+ scsi_host_alloc() -->
	149	+ scsi_add_host() ---->
	150	+ scsi_scan_host() -------+
	151	+ \|
	152	+ slave_alloc()
	153	+ slave_configure() --> scsi_change_queue_depth()
	154	+ \|
	155	+ slave_alloc()
	156	+ slave_configure()
	157	+ \|
	158	+ slave_alloc() ***
	159	+ slave_destroy() ***
	160	+
	161	+
	162	+ *** For scsi devices that the mid level tries to scan but do not
	163	+ respond, a slave_alloc(), slave_destroy() pair is called.
	164	+
	165	+If the LLD wants to adjust the default queue settings, it can invoke
	166	+scsi_change_queue_depth() in its slave_configure() routine.
	167	+
	168	+When an HBA is being removed it could be as part of an orderly shutdown
	169	+associated with the LLD module being unloaded (e.g. with the "rmmod"
	170	+command) or in response to a "hot unplug" indicated by sysfs()'s
	171	+remove() callback being invoked. In either case, the sequence is the
	172	+same::
	173	+
	174	+ HBA REMOVE: assume 2 SCSI devices attached
	175	+ LLD mid level LLD
	176	+ ===----------------------=========-----------------===------
	177	+ scsi_remove_host() ---------+
	178	+ \|
	179	+ slave_destroy()
	180	+ slave_destroy()
	181	+ scsi_host_put()
	182	+
	183	+It may be useful for a LLD to keep track of struct Scsi_Host instances
	184	+(a pointer is returned by scsi_host_alloc()). Such instances are "owned"
	185	+by the mid-level. struct Scsi_Host instances are freed from
	186	+scsi_host_put() when the reference count hits zero.
	187	+
	188	+Hot unplugging an HBA that controls a disk which is processing SCSI
	189	+commands on a mounted file system is an interesting situation. Reference
	190	+counting logic is being introduced into the mid level to cope with many
	191	+of the issues involved. See the section on reference counting below.
	192	+
	193	+
	194	+The hotplug concept may be extended to SCSI devices. Currently, when an
	195	+HBA is added, the scsi_scan_host() function causes a scan for SCSI devices
	196	+attached to the HBA's SCSI transport. On newer SCSI transports the HBA
	197	+may become aware of a new SCSI device _after_ the scan has completed.
	198	+An LLD can use this sequence to make the mid level aware of a SCSI device::
	199	+
	200	+ SCSI DEVICE hotplug
	201	+ LLD mid level LLD
	202	+ ===-------------------=========--------------------===------
	203	+ scsi_add_device() ------+
	204	+ \|
	205	+ slave_alloc()
	206	+ slave_configure() [--> scsi_change_queue_depth()]
	207	+
	208	+In a similar fashion, an LLD may become aware that a SCSI device has been
	209	+removed (unplugged) or the connection to it has been interrupted. Some
	210	+existing SCSI transports (e.g. SPI) may not become aware that a SCSI
	211	+device has been removed until a subsequent SCSI command fails which will
	212	+probably cause that device to be set offline by the mid level. An LLD that
	213	+detects the removal of a SCSI device can instigate its removal from
	214	+upper layers with this sequence::
	215	+
	216	+ SCSI DEVICE hot unplug
	217	+ LLD mid level LLD
	218	+ ===----------------------=========-----------------===------
	219	+ scsi_remove_device() -------+
	220	+ \|
	221	+ slave_destroy()
	222	+
	223	+It may be useful for an LLD to keep track of struct scsi_device instances
	224	+(a pointer is passed as the parameter to slave_alloc() and
	225	+slave_configure() callbacks). Such instances are "owned" by the mid-level.
	226	+struct scsi_device instances are freed after slave_destroy().
	227	+
	228	+
	229	+Reference Counting
	230	+==================
	231	+The Scsi_Host structure has had reference counting infrastructure added.
	232	+This effectively spreads the ownership of struct Scsi_Host instances
	233	+across the various SCSI layers which use them. Previously such instances
	234	+were exclusively owned by the mid level. LLDs would not usually need to
	235	+directly manipulate these reference counts but there may be some cases
	236	+where they do.
	237	+
	238	+There are 3 reference counting functions of interest associated with
	239	+struct Scsi_Host:
	240	+
	241	+ - scsi_host_alloc():
	242	+ returns a pointer to new instance of struct
	243	+ Scsi_Host which has its reference count ^^ set to 1
	244	+
	245	+ - scsi_host_get():
	246	+ adds 1 to the reference count of the given instance
	247	+
	248	+ - scsi_host_put():
	249	+ decrements 1 from the reference count of the given
	250	+ instance. If the reference count reaches 0 then the given instance
	251	+ is freed
	252	+
	253	+The scsi_device structure has had reference counting infrastructure added.
	254	+This effectively spreads the ownership of struct scsi_device instances
	255	+across the various SCSI layers which use them. Previously such instances
	256	+were exclusively owned by the mid level. See the access functions declared
	257	+towards the end of include/scsi/scsi_device.h . If an LLD wants to keep
	258	+a copy of a pointer to a scsi_device instance it should use scsi_device_get()
	259	+to bump its reference count. When it is finished with the pointer it can
	260	+use scsi_device_put() to decrement its reference count (and potentially
	261	+delete it).
	262	+
	263	+.. Note::
	264	+
	265	+ struct Scsi_Host actually has 2 reference counts which are manipulated
	266	+ in parallel by these functions.
	267	+
	268	+
	269	+Conventions
	270	+===========
	271	+First, Linus Torvalds's thoughts on C coding style can be found in the
	272	+Documentation/process/coding-style.rst file.
	273	+
	274	+Next, there is a movement to "outlaw" typedefs introducing synonyms for
	275	+struct tags. Both can be still found in the SCSI subsystem, but
	276	+the typedefs have been moved to a single file, scsi_typedefs.h to
	277	+make their future removal easier, for example:
	278	+"typedef struct scsi_cmnd Scsi_Cmnd;"
	279	+
	280	+Also, most C99 enhancements are encouraged to the extent they are supported
	281	+by the relevant gcc compilers. So C99 style structure and array
	282	+initializers are encouraged where appropriate. Don't go too far,
	283	+VLAs are not properly supported yet. An exception to this is the use of
	284	+``//`` style comments; ``/.../`` comments are still preferred in Linux.
	285	+
	286	+Well written, tested and documented code, need not be re-formatted to
	287	+comply with the above conventions. For example, the aic7xxx driver
	288	+comes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD
	289	+and Adaptec have their own coding conventions.
	290	+
	291	+
	292	+Mid level supplied functions
	293	+============================
	294	+These functions are supplied by the SCSI mid level for use by LLDs.
	295	+The names (i.e. entry points) of these functions are exported
	296	+so an LLD that is a module can access them. The kernel will
	297	+arrange for the SCSI mid level to be loaded and initialized before any LLD
	298	+is initialized. The functions below are listed alphabetically and their
	299	+names all start with ``scsi_``.
	300	+
	301	+Summary:
	302	+
	303	+ - scsi_add_device - creates new scsi device (lu) instance
	304	+ - scsi_add_host - perform sysfs registration and set up transport class
	305	+ - scsi_change_queue_depth - change the queue depth on a SCSI device
	306	+ - scsi_bios_ptable - return copy of block device's partition table
	307	+ - scsi_block_requests - prevent further commands being queued to given host
	308	+ - scsi_host_alloc - return a new scsi_host instance whose refcount==1
	309	+ - scsi_host_get - increments Scsi_Host instance's refcount
	310	+ - scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
	311	+ - scsi_partsize - parse partition table into cylinders, heads + sectors
	312	+ - scsi_register - create and register a scsi host adapter instance.
	313	+ - scsi_remove_device - detach and remove a SCSI device
	314	+ - scsi_remove_host - detach and remove all SCSI devices owned by host
	315	+ - scsi_report_bus_reset - report scsi _bus_ reset observed
	316	+ - scsi_scan_host - scan SCSI bus
	317	+ - scsi_track_queue_full - track successive QUEUE_FULL events
	318	+ - scsi_unblock_requests - allow further commands to be queued to given host
	319	+ - scsi_unregister - [calls scsi_host_put()]
	320	+
	321	+
	322	+Details::
	323	+
	324	+ /**
	325	+ * scsi_add_device - creates new scsi device (lu) instance
	326	+ * @shost: pointer to scsi host instance
	327	+ * @channel: channel number (rarely other than 0)
	328	+ * @id: target id number
	329	+ * @lun: logical unit number
	330	+ *
	331	+ * Returns pointer to new struct scsi_device instance or
	332	+ * ERR_PTR(-ENODEV) (or some other bent pointer) if something is
	333	+ * wrong (e.g. no lu responds at given address)
	334	+ *
	335	+ * Might block: yes
	336	+ *
	337	+ * Notes: This call is usually performed internally during a scsi
	338	+ * bus scan when an HBA is added (i.e. scsi_scan_host()). So it
	339	+ * should only be called if the HBA becomes aware of a new scsi
	340	+ * device (lu) after scsi_scan_host() has completed. If successful
	341	+ * this call can lead to slave_alloc() and slave_configure() callbacks
	342	+ * into the LLD.
	343	+ *
	344	+ * Defined in: drivers/scsi/scsi_scan.c
	345	+ **/
	346	+ struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
	347	+ unsigned int channel,
	348	+ unsigned int id, unsigned int lun)
	349	+
	350	+
	351	+ /**
	352	+ * scsi_add_host - perform sysfs registration and set up transport class
	353	+ * @shost: pointer to scsi host instance
	354	+ * @dev: pointer to struct device of type scsi class
	355	+ *
	356	+ * Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
	357	+ *
	358	+ * Might block: no
	359	+ *
	360	+ * Notes: Only required in "hotplug initialization model" after a
	361	+ * successful call to scsi_host_alloc(). This function does not
	362	+ * scan the bus; this can be done by calling scsi_scan_host() or
	363	+ * in some other transport-specific way. The LLD must set up
	364	+ * the transport template before calling this function and may only
	365	+ * access the transport class data after this function has been called.
	366	+ *
	367	+ * Defined in: drivers/scsi/hosts.c
	368	+ **/
	369	+ int scsi_add_host(struct Scsi_Host shost, struct device dev)
	370	+
	371	+
	372	+ /**
	373	+ * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
	374	+ * @sdev: pointer to SCSI device to change queue depth on
	375	+ * @tags Number of tags allowed if tagged queuing enabled,
	376	+ * or number of commands the LLD can queue up
	377	+ * in non-tagged mode (as per cmd_per_lun).
	378	+ *
	379	+ * Returns nothing
	380	+ *
	381	+ * Might block: no
	382	+ *
	383	+ * Notes: Can be invoked any time on a SCSI device controlled by this
	384	+ * LLD. [Specifically during and after slave_configure() and prior to
	385	+ * slave_destroy().] Can safely be invoked from interrupt code.
	386	+ *
	387	+ * Defined in: drivers/scsi/scsi.c [see source code for more notes]
	388	+ *
	389	+ **/
	390	+ int scsi_change_queue_depth(struct scsi_device *sdev, int tags)
	391	+
	392	+
	393	+ /**
	394	+ * scsi_bios_ptable - return copy of block device's partition table
	395	+ * @dev: pointer to block device
	396	+ *
	397	+ * Returns pointer to partition table, or NULL for failure
	398	+ *
	399	+ * Might block: yes
	400	+ *
	401	+ * Notes: Caller owns memory returned (free with kfree() )
	402	+ *
	403	+ * Defined in: drivers/scsi/scsicam.c
	404	+ **/
	405	+ unsigned char scsi_bios_ptable(struct block_device dev)
	406	+
	407	+
	408	+ /**
	409	+ * scsi_block_requests - prevent further commands being queued to given host
	410	+ *
	411	+ * @shost: pointer to host to block commands on
	412	+ *
	413	+ * Returns nothing
	414	+ *
	415	+ * Might block: no
	416	+ *
	417	+ * Notes: There is no timer nor any other means by which the requests
	418	+ * get unblocked other than the LLD calling scsi_unblock_requests().
	419	+ *
	420	+ * Defined in: drivers/scsi/scsi_lib.c
	421	+ **/
	422	+ void scsi_block_requests(struct Scsi_Host * shost)
	423	+
	424	+
	425	+ /**
	426	+ * scsi_host_alloc - create a scsi host adapter instance and perform basic
	427	+ * initialization.
	428	+ * @sht: pointer to scsi host template
	429	+ * @privsize: extra bytes to allocate in hostdata array (which is the
	430	+ * last member of the returned Scsi_Host instance)
	431	+ *
	432	+ * Returns pointer to new Scsi_Host instance or NULL on failure
	433	+ *
	434	+ * Might block: yes
	435	+ *
	436	+ * Notes: When this call returns to the LLD, the SCSI bus scan on
	437	+ * this host has _not_ yet been done.
	438	+ * The hostdata array (by default zero length) is a per host scratch
	439	+ * area for the LLD's exclusive use.
	440	+ * Both associated refcounting objects have their refcount set to 1.
	441	+ * Full registration (in sysfs) and a bus scan are performed later when
	442	+ * scsi_add_host() and scsi_scan_host() are called.
	443	+ *
	444	+ * Defined in: drivers/scsi/hosts.c .
	445	+ **/
	446	+ struct Scsi_Host * scsi_host_alloc(struct scsi_host_template * sht,
	447	+ int privsize)
	448	+
	449	+
	450	+ /**
	451	+ * scsi_host_get - increment Scsi_Host instance refcount
	452	+ * @shost: pointer to struct Scsi_Host instance
	453	+ *
	454	+ * Returns nothing
	455	+ *
	456	+ * Might block: currently may block but may be changed to not block
	457	+ *
	458	+ * Notes: Actually increments the counts in two sub-objects
	459	+ *
	460	+ * Defined in: drivers/scsi/hosts.c
	461	+ **/
	462	+ void scsi_host_get(struct Scsi_Host *shost)
	463	+
	464	+
	465	+ /**
	466	+ * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
	467	+ * @shost: pointer to struct Scsi_Host instance
	468	+ *
	469	+ * Returns nothing
	470	+ *
	471	+ * Might block: currently may block but may be changed to not block
	472	+ *
	473	+ * Notes: Actually decrements the counts in two sub-objects. If the
	474	+ * latter refcount reaches 0, the Scsi_Host instance is freed.
	475	+ * The LLD need not worry exactly when the Scsi_Host instance is
	476	+ * freed, it just shouldn't access the instance after it has balanced
	477	+ * out its refcount usage.
	478	+ *
	479	+ * Defined in: drivers/scsi/hosts.c
	480	+ **/
	481	+ void scsi_host_put(struct Scsi_Host *shost)
	482	+
	483	+
	484	+ /**
	485	+ * scsi_partsize - parse partition table into cylinders, heads + sectors
	486	+ * @buf: pointer to partition table
	487	+ * @capacity: size of (total) disk in 512 byte sectors
	488	+ * @cyls: outputs number of cylinders calculated via this pointer
	489	+ * @hds: outputs number of heads calculated via this pointer
	490	+ * @secs: outputs number of sectors calculated via this pointer
	491	+ *
	492	+ * Returns 0 on success, -1 on failure
	493	+ *
	494	+ * Might block: no
	495	+ *
	496	+ * Notes: Caller owns memory returned (free with kfree() )
	497	+ *
	498	+ * Defined in: drivers/scsi/scsicam.c
	499	+ **/
	500	+ int scsi_partsize(unsigned char *buf, unsigned long capacity,
	501	+ unsigned int cyls, unsigned int hds, unsigned int *secs)
	502	+
	503	+
	504	+ /**
	505	+ * scsi_register - create and register a scsi host adapter instance.
	506	+ * @sht: pointer to scsi host template
	507	+ * @privsize: extra bytes to allocate in hostdata array (which is the
	508	+ * last member of the returned Scsi_Host instance)
	509	+ *
	510	+ * Returns pointer to new Scsi_Host instance or NULL on failure
	511	+ *
	512	+ * Might block: yes
	513	+ *
	514	+ * Notes: When this call returns to the LLD, the SCSI bus scan on
	515	+ * this host has _not_ yet been done.
	516	+ * The hostdata array (by default zero length) is a per host scratch
	517	+ * area for the LLD.
	518	+ *
	519	+ * Defined in: drivers/scsi/hosts.c .
	520	+ **/
	521	+ struct Scsi_Host * scsi_register(struct scsi_host_template * sht,
	522	+ int privsize)
	523	+
	524	+
	525	+ /**
	526	+ * scsi_remove_device - detach and remove a SCSI device
	527	+ * @sdev: a pointer to a scsi device instance
	528	+ *
	529	+ * Returns value: 0 on success, -EINVAL if device not attached
	530	+ *
	531	+ * Might block: yes
	532	+ *
	533	+ * Notes: If an LLD becomes aware that a scsi device (lu) has
	534	+ * been removed but its host is still present then it can request
	535	+ * the removal of that scsi device. If successful this call will
	536	+ * lead to the slave_destroy() callback being invoked. sdev is an
	537	+ * invalid pointer after this call.
	538	+ *
	539	+ * Defined in: drivers/scsi/scsi_sysfs.c .
	540	+ **/
	541	+ int scsi_remove_device(struct scsi_device *sdev)
	542	+
	543	+
	544	+ /**
	545	+ * scsi_remove_host - detach and remove all SCSI devices owned by host
	546	+ * @shost: a pointer to a scsi host instance
	547	+ *
	548	+ * Returns value: 0 on success, 1 on failure (e.g. LLD busy ??)
	549	+ *
	550	+ * Might block: yes
	551	+ *
	552	+ * Notes: Should only be invoked if the "hotplug initialization
	553	+ * model" is being used. It should be called _prior_ to
	554	+ * scsi_unregister().
	555	+ *
	556	+ * Defined in: drivers/scsi/hosts.c .
	557	+ **/
	558	+ int scsi_remove_host(struct Scsi_Host *shost)
	559	+
	560	+
	561	+ /**
	562	+ * scsi_report_bus_reset - report scsi _bus_ reset observed
	563	+ * @shost: a pointer to a scsi host involved
	564	+ * @channel: channel (within) host on which scsi bus reset occurred
	565	+ *
	566	+ * Returns nothing
	567	+ *
	568	+ * Might block: no
	569	+ *
	570	+ * Notes: This only needs to be called if the reset is one which
	571	+ * originates from an unknown location. Resets originated by the
	572	+ * mid level itself don't need to call this, but there should be
	573	+ * no harm. The main purpose of this is to make sure that a
	574	+ * CHECK_CONDITION is properly treated.
	575	+ *
	576	+ * Defined in: drivers/scsi/scsi_error.c .
	577	+ **/
	578	+ void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
	579	+
	580	+
	581	+ /**
	582	+ * scsi_scan_host - scan SCSI bus
	583	+ * @shost: a pointer to a scsi host instance
	584	+ *
	585	+ * Might block: yes
	586	+ *
	587	+ * Notes: Should be called after scsi_add_host()
	588	+ *
	589	+ * Defined in: drivers/scsi/scsi_scan.c
	590	+ **/
	591	+ void scsi_scan_host(struct Scsi_Host *shost)
	592	+
	593	+
	594	+ /**
	595	+ * scsi_track_queue_full - track successive QUEUE_FULL events on given
	596	+ * device to determine if and when there is a need
	597	+ * to adjust the queue depth on the device.
	598	+ * @sdev: pointer to SCSI device instance
	599	+ * @depth: Current number of outstanding SCSI commands on this device,
	600	+ * not counting the one returned as QUEUE_FULL.
	601	+ *
	602	+ * Returns 0 - no change needed
	603	+ * >0 - adjust queue depth to this new depth
	604	+ * -1 - drop back to untagged operation using host->cmd_per_lun
	605	+ * as the untagged command depth
	606	+ *
	607	+ * Might block: no
	608	+ *
	609	+ * Notes: LLDs may call this at any time and we will do "The Right
	610	+ * Thing"; interrupt context safe.
	611	+ *
	612	+ * Defined in: drivers/scsi/scsi.c .
	613	+ **/
	614	+ int scsi_track_queue_full(struct scsi_device *sdev, int depth)
	615	+
	616	+
	617	+ /**
	618	+ * scsi_unblock_requests - allow further commands to be queued to given host
	619	+ *
	620	+ * @shost: pointer to host to unblock commands on
	621	+ *
	622	+ * Returns nothing
	623	+ *
	624	+ * Might block: no
	625	+ *
	626	+ * Defined in: drivers/scsi/scsi_lib.c .
	627	+ **/
	628	+ void scsi_unblock_requests(struct Scsi_Host * shost)
	629	+
	630	+
	631	+ /**
	632	+ * scsi_unregister - unregister and free memory used by host instance
	633	+ * @shp: pointer to scsi host instance to unregister.
	634	+ *
	635	+ * Returns nothing
	636	+ *
	637	+ * Might block: no
	638	+ *
	639	+ * Notes: Should not be invoked if the "hotplug initialization
	640	+ * model" is being used. Called internally by exit_this_scsi_driver()
	641	+ * in the "passive initialization model". Hence a LLD has no need to
	642	+ * call this function directly.
	643	+ *
	644	+ * Defined in: drivers/scsi/hosts.c .
	645	+ **/
	646	+ void scsi_unregister(struct Scsi_Host * shp)
	647	+
	648	+
	649	+
	650	+
	651	+Interface Functions
	652	+===================
	653	+Interface functions are supplied (defined) by LLDs and their function
	654	+pointers are placed in an instance of struct scsi_host_template which
	655	+is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()].
	656	+Some are mandatory. Interface functions should be declared static. The
	657	+accepted convention is that driver "xyz" will declare its slave_configure()
	658	+function as::
	659	+
	660	+ static int xyz_slave_configure(struct scsi_device * sdev);
	661	+
	662	+and so forth for all interface functions listed below.
	663	+
	664	+A pointer to this function should be placed in the 'slave_configure' member
	665	+of a "struct scsi_host_template" instance. A pointer to such an instance
	666	+should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
	667	+init_this_scsi_driver()].
	668	+
	669	+The interface functions are also described in the include/scsi/scsi_host.h
	670	+file immediately above their definition point in "struct scsi_host_template".
	671	+In some cases more detail is given in scsi_host.h than below.
	672	+
	673	+The interface functions are listed below in alphabetical order.
	674	+
	675	+Summary:
	676	+
	677	+ - bios_param - fetch head, sector, cylinder info for a disk
	678	+ - eh_timed_out - notify the host that a command timer expired
	679	+ - eh_abort_handler - abort given command
	680	+ - eh_bus_reset_handler - issue SCSI bus reset
	681	+ - eh_device_reset_handler - issue SCSI device reset
	682	+ - eh_host_reset_handler - reset host (host bus adapter)
	683	+ - info - supply information about given host
	684	+ - ioctl - driver can respond to ioctls
	685	+ - proc_info - supports /proc/scsi/{driver_name}/{host_no}
	686	+ - queuecommand - queue scsi command, invoke 'done' on completion
	687	+ - slave_alloc - prior to any commands being sent to a new device
	688	+ - slave_configure - driver fine tuning for given device after attach
	689	+ - slave_destroy - given device is about to be shut down
	690	+
	691	+
	692	+Details::
	693	+
	694	+ /**
	695	+ * bios_param - fetch head, sector, cylinder info for a disk
	696	+ * @sdev: pointer to scsi device context (defined in
	697	+ * include/scsi/scsi_device.h)
	698	+ * @bdev: pointer to block device context (defined in fs.h)
	699	+ * @capacity: device size (in 512 byte sectors)
	700	+ * @params: three element array to place output:
	701	+ * params[0] number of heads (max 255)
	702	+ * params[1] number of sectors (max 63)
	703	+ * params[2] number of cylinders
	704	+ *
	705	+ * Return value is ignored
	706	+ *
	707	+ * Locks: none
	708	+ *
	709	+ * Calling context: process (sd)
	710	+ *
	711	+ * Notes: an arbitrary geometry (based on READ CAPACITY) is used
	712	+ * if this function is not provided. The params array is
	713	+ * pre-initialized with made up values just in case this function
	714	+ * doesn't output anything.
	715	+ *
	716	+ * Optionally defined in: LLD
	717	+ **/
	718	+ int bios_param(struct scsi_device * sdev, struct block_device *bdev,
	719	+ sector_t capacity, int params[3])
	720	+
	721	+
	722	+ /**
	723	+ * eh_timed_out - The timer for the command has just fired
	724	+ * @scp: identifies command timing out
	725	+ *
	726	+ * Returns:
	727	+ *
	728	+ * EH_HANDLED: I fixed the error, please complete the command
	729	+ * EH_RESET_TIMER: I need more time, reset the timer and
	730	+ * begin counting again
	731	+ * EH_NOT_HANDLED Begin normal error recovery
	732	+ *
	733	+ *
	734	+ * Locks: None held
	735	+ *
	736	+ * Calling context: interrupt
	737	+ *
	738	+ * Notes: This is to give the LLD an opportunity to do local recovery.
	739	+ * This recovery is limited to determining if the outstanding command
	740	+ * will ever complete. You may not abort and restart the command from
	741	+ * this callback.
	742	+ *
	743	+ * Optionally defined in: LLD
	744	+ **/
	745	+ int eh_timed_out(struct scsi_cmnd * scp)
	746	+
	747	+
	748	+ /**
	749	+ * eh_abort_handler - abort command associated with scp
	750	+ * @scp: identifies command to be aborted
	751	+ *
	752	+ * Returns SUCCESS if command aborted else FAILED
	753	+ *
	754	+ * Locks: None held
	755	+ *
	756	+ * Calling context: kernel thread
	757	+ *
	758	+ * Notes: If 'no_async_abort' is defined this callback
	759	+ * will be invoked from scsi_eh thread. No other commands
	760	+ * will then be queued on current host during eh.
	761	+ * Otherwise it will be called whenever scsi_times_out()
	762	+ * is called due to a command timeout.
	763	+ *
	764	+ * Optionally defined in: LLD
	765	+ **/
	766	+ int eh_abort_handler(struct scsi_cmnd * scp)
	767	+
	768	+
	769	+ /**
	770	+ * eh_bus_reset_handler - issue SCSI bus reset
	771	+ * @scp: SCSI bus that contains this device should be reset
	772	+ *
	773	+ * Returns SUCCESS if command aborted else FAILED
	774	+ *
	775	+ * Locks: None held
	776	+ *
	777	+ * Calling context: kernel thread
	778	+ *
	779	+ * Notes: Invoked from scsi_eh thread. No other commands will be
	780	+ * queued on current host during eh.
	781	+ *
	782	+ * Optionally defined in: LLD
	783	+ **/
	784	+ int eh_bus_reset_handler(struct scsi_cmnd * scp)
	785	+
	786	+
	787	+ /**
	788	+ * eh_device_reset_handler - issue SCSI device reset
	789	+ * @scp: identifies SCSI device to be reset
	790	+ *
	791	+ * Returns SUCCESS if command aborted else FAILED
	792	+ *
	793	+ * Locks: None held
	794	+ *
	795	+ * Calling context: kernel thread
	796	+ *
	797	+ * Notes: Invoked from scsi_eh thread. No other commands will be
	798	+ * queued on current host during eh.
	799	+ *
	800	+ * Optionally defined in: LLD
	801	+ **/
	802	+ int eh_device_reset_handler(struct scsi_cmnd * scp)
	803	+
	804	+
	805	+ /**
	806	+ * eh_host_reset_handler - reset host (host bus adapter)
	807	+ * @scp: SCSI host that contains this device should be reset
	808	+ *
	809	+ * Returns SUCCESS if command aborted else FAILED
	810	+ *
	811	+ * Locks: None held
	812	+ *
	813	+ * Calling context: kernel thread
	814	+ *
	815	+ * Notes: Invoked from scsi_eh thread. No other commands will be
	816	+ * queued on current host during eh.
	817	+ * With the default eh_strategy in place, if none of the _abort_,
	818	+ * _device_reset_, _bus_reset_ or this eh handler function are
	819	+ * defined (or they all return FAILED) then the device in question
	820	+ * will be set offline whenever eh is invoked.
	821	+ *
	822	+ * Optionally defined in: LLD
	823	+ **/
	824	+ int eh_host_reset_handler(struct scsi_cmnd * scp)
	825	+
	826	+
	827	+ /**
	828	+ * info - supply information about given host: driver name plus data
	829	+ * to distinguish given host
	830	+ * @shp: host to supply information about
	831	+ *
	832	+ * Return ASCII null terminated string. [This driver is assumed to
	833	+ * manage the memory pointed to and maintain it, typically for the
	834	+ * lifetime of this host.]
	835	+ *
	836	+ * Locks: none
	837	+ *
	838	+ * Calling context: process
	839	+ *
	840	+ * Notes: Often supplies PCI or ISA information such as IO addresses
	841	+ * and interrupt numbers. If not supplied struct Scsi_Host::name used
	842	+ * instead. It is assumed the returned information fits on one line
	843	+ * (i.e. does not included embedded newlines).
	844	+ * The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this
	845	+ * function (or struct Scsi_Host::name if this function is not
	846	+ * available).
	847	+ * In a similar manner, init_this_scsi_driver() outputs to the console
	848	+ * each host's "info" (or name) for the driver it is registering.
	849	+ * Also if proc_info() is not supplied, the output of this function
	850	+ * is used instead.
	851	+ *
	852	+ * Optionally defined in: LLD
	853	+ **/
	854	+ const char * info(struct Scsi_Host * shp)
	855	+
	856	+
	857	+ /**
	858	+ * ioctl - driver can respond to ioctls
	859	+ * @sdp: device that ioctl was issued for
	860	+ * @cmd: ioctl number
	861	+ * @arg: pointer to read or write data from. Since it points to
	862	+ * user space, should use appropriate kernel functions
	863	+ * (e.g. copy_from_user() ). In the Unix style this argument
	864	+ * can also be viewed as an unsigned long.
	865	+ *
	866	+ * Returns negative "errno" value when there is a problem. 0 or a
	867	+ * positive value indicates success and is returned to the user space.
	868	+ *
	869	+ * Locks: none
	870	+ *
	871	+ * Calling context: process
	872	+ *
	873	+ * Notes: The SCSI subsystem uses a "trickle down" ioctl model.
	874	+ * The user issues an ioctl() against an upper level driver
	875	+ * (e.g. /dev/sdc) and if the upper level driver doesn't recognize
	876	+ * the 'cmd' then it is passed to the SCSI mid level. If the SCSI
	877	+ * mid level does not recognize it, then the LLD that controls
	878	+ * the device receives the ioctl. According to recent Unix standards
	879	+ * unsupported ioctl() 'cmd' numbers should return -ENOTTY.
	880	+ *
	881	+ * Optionally defined in: LLD
	882	+ **/
	883	+ int ioctl(struct scsi_device sdp, int cmd, void arg)
	884	+
	885	+
	886	+ /**
	887	+ * proc_info - supports /proc/scsi/{driver_name}/{host_no}
	888	+ * @buffer: anchor point to output to (0==writeto1_read0) or fetch from
	889	+ * (1==writeto1_read0).
	890	+ * @start: where "interesting" data is written to. Ignored when
	891	+ * 1==writeto1_read0.
	892	+ * @offset: offset within buffer 0==writeto1_read0 is actually
	893	+ * interested in. Ignored when 1==writeto1_read0 .
	894	+ * @length: maximum (or actual) extent of buffer
	895	+ * @host_no: host number of interest (struct Scsi_Host::host_no)
	896	+ * @writeto1_read0: 1 -> data coming from user space towards driver
	897	+ * (e.g. "echo some_string > /proc/scsi/xyz/2")
	898	+ * 0 -> user what data from this driver
	899	+ * (e.g. "cat /proc/scsi/xyz/2")
	900	+ *
	901	+ * Returns length when 1==writeto1_read0. Otherwise number of chars
	902	+ * output to buffer past offset.
	903	+ *
	904	+ * Locks: none held
	905	+ *
	906	+ * Calling context: process
	907	+ *
	908	+ * Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs
	909	+ * support can now be configured out of the scsi subsystem.
	910	+ *
	911	+ * Optionally defined in: LLD
	912	+ **/
	913	+ int proc_info(char * buffer, char ** start, off_t offset,
	914	+ int length, int host_no, int writeto1_read0)
	915	+
	916	+
	917	+ /**
	918	+ * queuecommand - queue scsi command, invoke scp->scsi_done on completion
	919	+ * @shost: pointer to the scsi host object
	920	+ * @scp: pointer to scsi command object
	921	+ *
	922	+ * Returns 0 on success.
	923	+ *
	924	+ * If there's a failure, return either:
	925	+ *
	926	+ * SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
	927	+ * SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full
	928	+ *
	929	+ * On both of these returns, the mid-layer will requeue the I/O
	930	+ *
	931	+ * - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
	932	+ * device will be paused, and it will be unpaused when a command to
	933	+ * the device returns (or after a brief delay if there are no more
	934	+ * outstanding commands to it). Commands to other devices continue
	935	+ * to be processed normally.
	936	+ *
	937	+ * - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
	938	+ * is paused and will be unpaused when any command returns from
	939	+ * the host (or after a brief delay if there are no outstanding
	940	+ * commands to the host).
	941	+ *
	942	+ * For compatibility with earlier versions of queuecommand, any
	943	+ * other return value is treated the same as
	944	+ * SCSI_MLQUEUE_HOST_BUSY.
	945	+ *
	946	+ * Other types of errors that are detected immediately may be
	947	+ * flagged by setting scp->result to an appropriate value,
	948	+ * invoking the scp->scsi_done callback, and then returning 0
	949	+ * from this function. If the command is not performed
	950	+ * immediately (and the LLD is starting (or will start) the given
	951	+ * command) then this function should place 0 in scp->result and
	952	+ * return 0.
	953	+ *
	954	+ * Command ownership. If the driver returns zero, it owns the
	955	+ * command and must take responsibility for ensuring the
	956	+ * scp->scsi_done callback is executed. Note: the driver may
	957	+ * call scp->scsi_done before returning zero, but after it has
	958	+ * called scp->scsi_done, it may not return any value other than
	959	+ * zero. If the driver makes a non-zero return, it must not
	960	+ * execute the command's scsi_done callback at any time.
	961	+ *
	962	+ * Locks: up to and including 2.6.36, struct Scsi_Host::host_lock
	963	+ * held on entry (with "irqsave") and is expected to be
	964	+ * held on return. From 2.6.37 onwards, queuecommand is
	965	+ * called without any locks held.
	966	+ *
	967	+ * Calling context: in interrupt (soft irq) or process context
	968	+ *
	969	+ * Notes: This function should be relatively fast. Normally it
	970	+ * will not wait for IO to complete. Hence the scp->scsi_done
	971	+ * callback is invoked (often directly from an interrupt service
	972	+ * routine) some time after this function has returned. In some
	973	+ * cases (e.g. pseudo adapter drivers that manufacture the
	974	+ * response to a SCSI INQUIRY) the scp->scsi_done callback may be
	975	+ * invoked before this function returns. If the scp->scsi_done
	976	+ * callback is not invoked within a certain period the SCSI mid
	977	+ * level will commence error processing. If a status of CHECK
	978	+ * CONDITION is placed in "result" when the scp->scsi_done
	979	+ * callback is invoked, then the LLD driver should perform
	980	+ * autosense and fill in the struct scsi_cmnd::sense_buffer
	981	+ * array. The scsi_cmnd::sense_buffer array is zeroed prior to
	982	+ * the mid level queuing a command to an LLD.
	983	+ *
	984	+ * Defined in: LLD
	985	+ **/
	986	+ int queuecommand(struct Scsi_Host shost, struct scsi_cmnd scp)
	987	+
	988	+
	989	+ /**
	990	+ * slave_alloc - prior to any commands being sent to a new device
	991	+ * (i.e. just prior to scan) this call is made
	992	+ * @sdp: pointer to new device (about to be scanned)
	993	+ *
	994	+ * Returns 0 if ok. Any other return is assumed to be an error and
	995	+ * the device is ignored.
	996	+ *
	997	+ * Locks: none
	998	+ *
	999	+ * Calling context: process
	1000	+ *
	1001	+ * Notes: Allows the driver to allocate any resources for a device
	1002	+ * prior to its initial scan. The corresponding scsi device may not
	1003	+ * exist but the mid level is just about to scan for it (i.e. send
	1004	+ * and INQUIRY command plus ...). If a device is found then
	1005	+ * slave_configure() will be called while if a device is not found
	1006	+ * slave_destroy() is called.
	1007	+ * For more details see the include/scsi/scsi_host.h file.
	1008	+ *
	1009	+ * Optionally defined in: LLD
	1010	+ **/
	1011	+ int slave_alloc(struct scsi_device *sdp)
	1012	+
	1013	+
	1014	+ /**
	1015	+ * slave_configure - driver fine tuning for given device just after it
	1016	+ * has been first scanned (i.e. it responded to an
	1017	+ * INQUIRY)
	1018	+ * @sdp: device that has just been attached
	1019	+ *
	1020	+ * Returns 0 if ok. Any other return is assumed to be an error and
	1021	+ * the device is taken offline. [offline devices will _not_ have
	1022	+ * slave_destroy() called on them so clean up resources.]
	1023	+ *
	1024	+ * Locks: none
	1025	+ *
	1026	+ * Calling context: process
	1027	+ *
	1028	+ * Notes: Allows the driver to inspect the response to the initial
	1029	+ * INQUIRY done by the scanning code and take appropriate action.
	1030	+ * For more details see the include/scsi/scsi_host.h file.
	1031	+ *
	1032	+ * Optionally defined in: LLD
	1033	+ **/
	1034	+ int slave_configure(struct scsi_device *sdp)
	1035	+
	1036	+
	1037	+ /**
	1038	+ * slave_destroy - given device is about to be shut down. All
	1039	+ * activity has ceased on this device.
	1040	+ * @sdp: device that is about to be shut down
	1041	+ *
	1042	+ * Returns nothing
	1043	+ *
	1044	+ * Locks: none
	1045	+ *
	1046	+ * Calling context: process
	1047	+ *
	1048	+ * Notes: Mid level structures for given device are still in place
	1049	+ * but are about to be torn down. Any per device resources allocated
	1050	+ * by this driver for given device should be freed now. No further
	1051	+ * commands will be sent for this sdp instance. [However the device
	1052	+ * could be re-attached in the future in which case a new instance
	1053	+ * of struct scsi_device would be supplied by future slave_alloc()
	1054	+ * and slave_configure() calls.]
	1055	+ *
	1056	+ * Optionally defined in: LLD
	1057	+ **/
	1058	+ void slave_destroy(struct scsi_device *sdp)
	1059	+
	1060	+
	1061	+
	1062	+Data Structures
	1063	+===============
	1064	+struct scsi_host_template
	1065	+-------------------------
	1066	+There is one "struct scsi_host_template" instance per LLD [#]_. It is
	1067	+typically initialized as a file scope static in a driver's header file. That
	1068	+way members that are not explicitly initialized will be set to 0 or NULL.
	1069	+Member of interest:
	1070	+
	1071	+ name
	1072	+ - name of driver (may contain spaces, please limit to
	1073	+ less than 80 characters)
	1074	+
	1075	+ proc_name
	1076	+ - name used in "/proc/scsi/<proc_name>/<host_no>" and
	1077	+ by sysfs in one of its "drivers" directories. Hence
	1078	+ "proc_name" should only contain characters acceptable
	1079	+ to a Unix file name.
	1080	+
	1081	+ ``(*queuecommand)()``
	1082	+ - primary callback that the mid level uses to inject
	1083	+ SCSI commands into an LLD.
	1084	+
	1085	+The structure is defined and commented in include/scsi/scsi_host.h
	1086	+
	1087	+.. [#] In extreme situations a single driver may have several instances
	1088	+ if it controls several different classes of hardware (e.g. an LLD
	1089	+ that handles both ISA and PCI cards and has a separate instance of
	1090	+ struct scsi_host_template for each class).
	1091	+
	1092	+struct Scsi_Host
	1093	+----------------
	1094	+There is one struct Scsi_Host instance per host (HBA) that an LLD
	1095	+controls. The struct Scsi_Host structure has many members in common
	1096	+with "struct scsi_host_template". When a new struct Scsi_Host instance
	1097	+is created (in scsi_host_alloc() in hosts.c) those common members are
	1098	+initialized from the driver's struct scsi_host_template instance. Members
	1099	+of interest:
	1100	+
	1101	+ host_no
	1102	+ - system wide unique number that is used for identifying
	1103	+ this host. Issued in ascending order from 0.
	1104	+ can_queue
	1105	+ - must be greater than 0; do not send more than can_queue
	1106	+ commands to the adapter.
	1107	+ this_id
	1108	+ - scsi id of host (scsi initiator) or -1 if not known
	1109	+ sg_tablesize
	1110	+ - maximum scatter gather elements allowed by host.
	1111	+ Set this to SG_ALL or less to avoid chained SG lists.
	1112	+ Must be at least 1.
	1113	+ max_sectors
	1114	+ - maximum number of sectors (usually 512 bytes) allowed
	1115	+ in a single SCSI command. The default value of 0 leads
	1116	+ to a setting of SCSI_DEFAULT_MAX_SECTORS (defined in
	1117	+ scsi_host.h) which is currently set to 1024. So for a
	1118	+ disk the maximum transfer size is 512 KB when max_sectors
	1119	+ is not defined. Note that this size may not be sufficient
	1120	+ for disk firmware uploads.
	1121	+ cmd_per_lun
	1122	+ - maximum number of commands that can be queued on devices
	1123	+ controlled by the host. Overridden by LLD calls to
	1124	+ scsi_change_queue_depth().
	1125	+ unchecked_isa_dma
	1126	+ - 1=>only use bottom 16 MB of ram (ISA DMA addressing
	1127	+ restriction), 0=>can use full 32 bit (or better) DMA
	1128	+ address space
	1129	+ no_async_abort
	1130	+ - 1=>Asynchronous aborts are not supported
	1131	+ - 0=>Timed-out commands will be aborted asynchronously
	1132	+ hostt
	1133	+ - pointer to driver's struct scsi_host_template from which
	1134	+ this struct Scsi_Host instance was spawned
	1135	+ hostt->proc_name
	1136	+ - name of LLD. This is the driver name that sysfs uses
	1137	+ transportt
	1138	+ - pointer to driver's struct scsi_transport_template instance
	1139	+ (if any). FC and SPI transports currently supported.
	1140	+ sh_list
	1141	+ - a double linked list of pointers to all struct Scsi_Host
	1142	+ instances (currently ordered by ascending host_no)
	1143	+ my_devices
	1144	+ - a double linked list of pointers to struct scsi_device
	1145	+ instances that belong to this host.
	1146	+ hostdata[0]
	1147	+ - area reserved for LLD at end of struct Scsi_Host. Size
	1148	+ is set by the second argument (named 'xtr_bytes') to
	1149	+ scsi_host_alloc() or scsi_register().
	1150	+ vendor_id
	1151	+ - a unique value that identifies the vendor supplying
	1152	+ the LLD for the Scsi_Host. Used most often in validating
	1153	+ vendor-specific message requests. Value consists of an
	1154	+ identifier type and a vendor-specific value.
	1155	+ See scsi_netlink.h for a description of valid formats.
	1156	+
	1157	+The scsi_host structure is defined in include/scsi/scsi_host.h
	1158	+
	1159	+struct scsi_device
	1160	+------------------
	1161	+Generally, there is one instance of this structure for each SCSI logical unit
	1162	+on a host. Scsi devices connected to a host are uniquely identified by a
	1163	+channel number, target id and logical unit number (lun).
	1164	+The structure is defined in include/scsi/scsi_device.h
	1165	+
	1166	+struct scsi_cmnd
	1167	+----------------
	1168	+Instances of this structure convey SCSI commands to the LLD and responses
	1169	+back to the mid level. The SCSI mid level will ensure that no more SCSI
	1170	+commands become queued against the LLD than are indicated by
	1171	+scsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will
	1172	+be at least one instance of struct scsi_cmnd available for each SCSI device.
	1173	+Members of interest:
	1174	+
	1175	+ cmnd
	1176	+ - array containing SCSI command
	1177	+ cmnd_len
	1178	+ - length (in bytes) of SCSI command
	1179	+ sc_data_direction
	1180	+ - direction of data transfer in data phase. See
	1181	+ "enum dma_data_direction" in include/linux/dma-mapping.h
	1182	+ request_bufflen
	1183	+ - number of data bytes to transfer (0 if no data phase)
	1184	+ use_sg
	1185	+ - ==0 -> no scatter gather list, hence transfer data
	1186	+ to/from request_buffer
	1187	+ - >0 -> scatter gather list (actually an array) in
	1188	+ request_buffer with use_sg elements
	1189	+ request_buffer
	1190	+ - either contains data buffer or scatter gather list
	1191	+ depending on the setting of use_sg. Scatter gather
	1192	+ elements are defined by 'struct scatterlist' found
	1193	+ in include/linux/scatterlist.h .
	1194	+ done
	1195	+ - function pointer that should be invoked by LLD when the
	1196	+ SCSI command is completed (successfully or otherwise).
	1197	+ Should only be called by an LLD if the LLD has accepted
	1198	+ the command (i.e. queuecommand() returned or will return
	1199	+ 0). The LLD may invoke 'done' prior to queuecommand()
	1200	+ finishing.
	1201	+ result
	1202	+ - should be set by LLD prior to calling 'done'. A value
	1203	+ of 0 implies a successfully completed command (and all
	1204	+ data (if any) has been transferred to or from the SCSI
	1205	+ target device). 'result' is a 32 bit unsigned integer that
	1206	+ can be viewed as 4 related bytes. The SCSI status value is
	1207	+ in the LSB. See include/scsi/scsi.h status_byte(),
	1208	+ msg_byte(), host_byte() and driver_byte() macros and
	1209	+ related constants.
	1210	+ sense_buffer
	1211	+ - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
	1212	+ should be written when the SCSI status (LSB of 'result')
	1213	+ is set to CHECK_CONDITION (2). When CHECK_CONDITION is
	1214	+ set, if the top nibble of sense_buffer[0] has the value 7
	1215	+ then the mid level will assume the sense_buffer array
	1216	+ contains a valid SCSI sense buffer; otherwise the mid
	1217	+ level will issue a REQUEST_SENSE SCSI command to
	1218	+ retrieve the sense buffer. The latter strategy is error
	1219	+ prone in the presence of command queuing so the LLD should
	1220	+ always "auto-sense".
	1221	+ device
	1222	+ - pointer to scsi_device object that this command is
	1223	+ associated with.
	1224	+ resid
	1225	+ - an LLD should set this signed integer to the requested
	1226	+ transfer length (i.e. 'request_bufflen') less the number
	1227	+ of bytes that are actually transferred. 'resid' is
	1228	+ preset to 0 so an LLD can ignore it if it cannot detect
	1229	+ underruns (overruns should be rare). If possible an LLD
	1230	+ should set 'resid' prior to invoking 'done'. The most
	1231	+ interesting case is data transfers from a SCSI target
	1232	+ device (e.g. READs) that underrun.
	1233	+ underflow
	1234	+ - LLD should place (DID_ERROR << 16) in 'result' if
	1235	+ actual number of bytes transferred is less than this
	1236	+ figure. Not many LLDs implement this check and some that
	1237	+ do just output an error message to the log rather than
	1238	+ report a DID_ERROR. Better for an LLD to implement
	1239	+ 'resid'.
	1240	+
	1241	+It is recommended that a LLD set 'resid' on data transfers from a SCSI
	1242	+target device (e.g. READs). It is especially important that 'resid' is set
	1243	+when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR
	1244	+(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much
	1245	+data has been received then the safest approach is to indicate no bytes have
	1246	+been received. For example: to indicate that no valid data has been received
	1247	+a LLD might use these helpers::
	1248	+
	1249	+ scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
	1250	+
	1251	+where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512
	1252	+bytes blocks has been received 'resid' could be set like this::
	1253	+
	1254	+ scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
	1255	+
	1256	+The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h
	1257	+
	1258	+
	1259	+Locks
	1260	+=====
	1261	+Each struct Scsi_Host instance has a spin_lock called struct
	1262	+Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in
	1263	+hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
	1264	+is initialized to point at default_lock. Thereafter lock and unlock
	1265	+operations performed by the mid level use the struct Scsi_Host::host_lock
	1266	+pointer. Previously drivers could override the host_lock pointer but
	1267	+this is not allowed anymore.
	1268	+
	1269	+
	1270	+Autosense
	1271	+=========
	1272	+Autosense (or auto-sense) is defined in the SAM-2 document as "the
	1273	+automatic return of sense data to the application client coincident
	1274	+with the completion of a SCSI command" when a status of CHECK CONDITION
	1275	+occurs. LLDs should perform autosense. This should be done when the LLD
	1276	+detects a CHECK CONDITION status by either:
	1277	+
	1278	+ a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
	1279	+ to perform an extra data in phase on such responses
	1280	+ b) or, the LLD issuing a REQUEST SENSE command itself
	1281	+
	1282	+Either way, when a status of CHECK CONDITION is detected, the mid level
	1283	+decides whether the LLD has performed autosense by checking struct
	1284	+scsi_cmnd::sense_buffer[0] . If this byte has an upper nibble of 7 (or 0xf)
	1285	+then autosense is assumed to have taken place. If it has another value (and
	1286	+this byte is initialized to 0 before each command) then the mid level will
	1287	+issue a REQUEST SENSE command.
	1288	+
	1289	+In the presence of queued commands the "nexus" that maintains sense
	1290	+buffer data from the command that failed until a following REQUEST SENSE
	1291	+may get out of synchronization. This is why it is best for the LLD
	1292	+to perform autosense.
	1293	+
	1294	+
	1295	+Changes since lk 2.4 series
	1296	+===========================
	1297	+io_request_lock has been replaced by several finer grained locks. The lock
	1298	+relevant to LLDs is struct Scsi_Host::host_lock and there is
	1299	+one per SCSI host.
	1300	+
	1301	+The older error handling mechanism has been removed. This means the
	1302	+LLD interface functions abort() and reset() have been removed.
	1303	+The struct scsi_host_template::use_new_eh_code flag has been removed.
	1304	+
	1305	+In the 2.4 series the SCSI subsystem configuration descriptions were
	1306	+aggregated with the configuration descriptions from all other Linux
	1307	+subsystems in the Documentation/Configure.help file. In the 2.6 series,
	1308	+the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig
	1309	+file that contains both configuration and help information.
	1310	+
	1311	+struct SHT has been renamed to struct scsi_host_template.
	1312	+
	1313	+Addition of the "hotplug initialization model" and many extra functions
	1314	+to support it.
	1315	+
	1316	+
	1317	+Credits
	1318	+=======
	1319	+The following people have contributed to this document:
	1320	+
	1321	+ - Mike Anderson <andmike at us dot ibm dot com>
	1322	+ - James Bottomley <James dot Bottomley at hansenpartnership dot com>
	1323	+ - Patrick Mansfield <patmans at us dot ibm dot com>
	1324	+ - Christoph Hellwig <hch at infradead dot org>
	1325	+ - Doug Ledford <dledford at redhat dot com>
	1326	+ - Andries Brouwer <Andries dot Brouwer at cwi dot nl>
	1327	+ - Randy Dunlap <rdunlap at xenotime dot net>
	1328	+ - Alan Stern <stern at rowland dot harvard dot edu>
	1329	+
	1330	+
	1331	+Douglas Gilbert
	1332	+dgilbert at interlog dot com
	1333	+
	1334	+21st September 2004

Documentation/scsi/scsi_mid_low_api.txt+0−1280

@@ -1,1280 +0,0 @@
1		− Linux Kernel 2.6 series
2		− SCSI mid_level - lower_level driver interface
3		− =============================================
4		−
5		−Introduction
6		−============
7		−This document outlines the interface between the Linux SCSI mid level and
8		−SCSI lower level drivers. Lower level drivers (LLDs) are variously called
9		−host bus adapter (HBA) drivers and host drivers (HD). A "host" in this
10		−context is a bridge between a computer IO bus (e.g. PCI or ISA) and a
11		−single SCSI initiator port on a SCSI transport. An "initiator" port
12		−(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
13		−to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
14		−system, but only one per hardware type. Most LLDs can control one or more
15		−SCSI HBAs. Some HBAs contain multiple hosts.
16		−
17		−In some cases the SCSI transport is an external bus that already has
18		−its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
19		−SCSI subsystem LLD is a software bridge to the other driver subsystem.
20		−Examples are the usb-storage driver (found in the drivers/usb/storage
21		−directory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394
22		−directory).
23		−
24		−For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
25		−(SPI) controllers based on that company's 7xxx chip series. The aic7xxx
26		−LLD can be built into the kernel or loaded as a module. There can only be
27		−one aic7xxx LLD running in a Linux system but it may be controlling many
28		−HBAs. These HBAs might be either on PCI daughter-boards or built into
29		−the motherboard (or both). Some aic7xxx based HBAs are dual controllers
30		−and thus represent two hosts. Like most modern HBAs, each aic7xxx host
31		−has its own PCI device address. [The one-to-one correspondence between
32		−a SCSI host and a PCI device is common but not required (e.g. with
33		−ISA adapters).]
34		−
35		−The SCSI mid level isolates an LLD from other layers such as the SCSI
36		−upper layer drivers and the block layer.
37		−
38		−This version of the document roughly matches linux kernel version 2.6.8 .
39		−
40		−Documentation
41		−=============
42		−There is a SCSI documentation directory within the kernel source tree,
43		−typically Documentation/scsi . Most documents are in plain
44		−(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be
45		−found in that directory. A more recent copy of this document may be found
46		−at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/.
47		−Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
48		−briefly described in scsi.txt which contains a url to a document
49		−describing the SCSI subsystem in the lk 2.4 series. Two upper level
50		−drivers have documents in that directory: st.txt (SCSI tape driver) and
51		−scsi-generic.txt (for the sg driver).
52		−
53		−Some documentation (or urls) for LLDs may be found in the C source code
54		−or in the same directory as the C source code. For example to find a url
55		−about the USB mass storage driver see the
56		−/usr/src/linux/drivers/usb/storage directory.
57		−
58		−Driver structure
59		−================
60		−Traditionally an LLD for the SCSI subsystem has been at least two files in
61		−the drivers/scsi directory. For example, a driver called "xyz" has a header
62		−file "xyz.h" and a source file "xyz.c". [Actually there is no good reason
63		−why this couldn't all be in one file; the header file is superfluous.] Some
64		−drivers that have been ported to several operating systems have more than
65		−two files. For example the aic7xxx driver has separate files for generic
66		−and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
67		−their own directory under the drivers/scsi directory.
68		−
69		−When a new LLD is being added to Linux, the following files (found in the
70		−drivers/scsi directory) will need some attention: Makefile and Kconfig .
71		−It is probably best to study how existing LLDs are organized.
72		−
73		−As the 2.5 series development kernels evolve into the 2.6 series
74		−production series, changes are being introduced into this interface. An
75		−example of this is driver initialization code where there are now 2 models
76		−available. The older one, similar to what was found in the lk 2.4 series,
77		−is based on hosts that are detected at HBA driver load time. This will be
78		−referred to the "passive" initialization model. The newer model allows HBAs
79		−to be hot plugged (and unplugged) during the lifetime of the LLD and will
80		−be referred to as the "hotplug" initialization model. The newer model is
81		−preferred as it can handle both traditional SCSI equipment that is
82		−permanently connected as well as modern "SCSI" devices (e.g. USB or
83		−IEEE 1394 connected digital cameras) that are hotplugged. Both
84		−initialization models are discussed in the following sections.
85		−
86		−An LLD interfaces to the SCSI subsystem several ways:
87		− a) directly invoking functions supplied by the mid level
88		− b) passing a set of function pointers to a registration function
89		− supplied by the mid level. The mid level will then invoke these
90		− functions at some point in the future. The LLD will supply
91		− implementations of these functions.
92		− c) direct access to instances of well known data structures maintained
93		− by the mid level
94		−
95		−Those functions in group a) are listed in a section entitled "Mid level
96		−supplied functions" below.
97		−
98		−Those functions in group b) are listed in a section entitled "Interface
99		−functions" below. Their function pointers are placed in the members of
100		−"struct scsi_host_template", an instance of which is passed to
101		−scsi_host_alloc() ** . Those interface functions that the LLD does not
102		−wish to supply should have NULL placed in the corresponding member of
103		−struct scsi_host_template. Defining an instance of struct
104		−scsi_host_template at file scope will cause NULL to be placed in function
105		− pointer members not explicitly initialized.
106		−
107		−Those usages in group c) should be handled with care, especially in a
108		−"hotplug" environment. LLDs should be aware of the lifetime of instances
109		−that are shared with the mid level and other layers.
110		−
111		−All functions defined within an LLD and all data defined at file scope
112		−should be static. For example the slave_alloc() function in an LLD
113		−called "xxx" could be defined as
114		−"static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }"
115		−
116		−** the scsi_host_alloc() function is a replacement for the rather vaguely
117		−named scsi_register() function in most situations.
118		−
119		−
120		−Hotplug initialization model
121		−============================
122		−In this model an LLD controls when SCSI hosts are introduced and removed
123		−from the SCSI subsystem. Hosts can be introduced as early as driver
124		−initialization and removed as late as driver shutdown. Typically a driver
125		−will respond to a sysfs probe() callback that indicates an HBA has been
126		−detected. After confirming that the new device is one that the LLD wants
127		−to control, the LLD will initialize the HBA and then register a new host
128		−with the SCSI mid level.
129		−
130		−During LLD initialization the driver should register itself with the
131		−appropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus).
132		−This can probably be done via sysfs. Any driver parameters (especially
133		−those that are writable after the driver is loaded) could also be
134		−registered with sysfs at this point. The SCSI mid level first becomes
135		−aware of an LLD when that LLD registers its first HBA.
136		−
137		−At some later time, the LLD becomes aware of an HBA and what follows
138		−is a typical sequence of calls between the LLD and the mid level.
139		−This example shows the mid level scanning the newly introduced HBA for 3
140		−scsi devices of which only the first 2 respond:
141		−
142		− HBA PROBE: assume 2 SCSI devices found in scan
143		−LLD mid level LLD
144		−===-------------------=========--------------------===------
145		−scsi_host_alloc() -->
146		−scsi_add_host() ---->
147		−scsi_scan_host() -------+
148		− \|
149		− slave_alloc()
150		− slave_configure() --> scsi_change_queue_depth()
151		− \|
152		− slave_alloc()
153		− slave_configure()
154		− \|
155		− slave_alloc() ***
156		− slave_destroy() ***
157		−------------------------------------------------------------
158		−
159		−If the LLD wants to adjust the default queue settings, it can invoke
160		−scsi_change_queue_depth() in its slave_configure() routine.
161		−
162		−*** For scsi devices that the mid level tries to scan but do not
163		− respond, a slave_alloc(), slave_destroy() pair is called.
164		−
165		−When an HBA is being removed it could be as part of an orderly shutdown
166		−associated with the LLD module being unloaded (e.g. with the "rmmod"
167		−command) or in response to a "hot unplug" indicated by sysfs()'s
168		−remove() callback being invoked. In either case, the sequence is the
169		−same:
170		−
171		− HBA REMOVE: assume 2 SCSI devices attached
172		−LLD mid level LLD
173		−===----------------------=========-----------------===------
174		−scsi_remove_host() ---------+
175		− \|
176		− slave_destroy()
177		− slave_destroy()
178		−scsi_host_put()
179		−------------------------------------------------------------
180		−
181		−It may be useful for a LLD to keep track of struct Scsi_Host instances
182		−(a pointer is returned by scsi_host_alloc()). Such instances are "owned"
183		−by the mid-level. struct Scsi_Host instances are freed from
184		−scsi_host_put() when the reference count hits zero.
185		−
186		−Hot unplugging an HBA that controls a disk which is processing SCSI
187		−commands on a mounted file system is an interesting situation. Reference
188		−counting logic is being introduced into the mid level to cope with many
189		−of the issues involved. See the section on reference counting below.
190		−
191		−
192		−The hotplug concept may be extended to SCSI devices. Currently, when an
193		−HBA is added, the scsi_scan_host() function causes a scan for SCSI devices
194		−attached to the HBA's SCSI transport. On newer SCSI transports the HBA
195		−may become aware of a new SCSI device _after_ the scan has completed.
196		−An LLD can use this sequence to make the mid level aware of a SCSI device:
197		−
198		− SCSI DEVICE hotplug
199		−LLD mid level LLD
200		−===-------------------=========--------------------===------
201		−scsi_add_device() ------+
202		− \|
203		− slave_alloc()
204		− slave_configure() [--> scsi_change_queue_depth()]
205		−------------------------------------------------------------
206		−
207		−In a similar fashion, an LLD may become aware that a SCSI device has been
208		−removed (unplugged) or the connection to it has been interrupted. Some
209		−existing SCSI transports (e.g. SPI) may not become aware that a SCSI
210		−device has been removed until a subsequent SCSI command fails which will
211		−probably cause that device to be set offline by the mid level. An LLD that
212		−detects the removal of a SCSI device can instigate its removal from
213		−upper layers with this sequence:
214		−
215		− SCSI DEVICE hot unplug
216		−LLD mid level LLD
217		−===----------------------=========-----------------===------
218		−scsi_remove_device() -------+
219		− \|
220		− slave_destroy()
221		−------------------------------------------------------------
222		−
223		−It may be useful for an LLD to keep track of struct scsi_device instances
224		−(a pointer is passed as the parameter to slave_alloc() and
225		−slave_configure() callbacks). Such instances are "owned" by the mid-level.
226		−struct scsi_device instances are freed after slave_destroy().
227		−
228		−
229		−Reference Counting
230		−==================
231		−The Scsi_Host structure has had reference counting infrastructure added.
232		−This effectively spreads the ownership of struct Scsi_Host instances
233		−across the various SCSI layers which use them. Previously such instances
234		−were exclusively owned by the mid level. LLDs would not usually need to
235		−directly manipulate these reference counts but there may be some cases
236		−where they do.
237		−
238		−There are 3 reference counting functions of interest associated with
239		−struct Scsi_Host:
240		− - scsi_host_alloc(): returns a pointer to new instance of struct
241		− Scsi_Host which has its reference count ^^ set to 1
242		− - scsi_host_get(): adds 1 to the reference count of the given instance
243		− - scsi_host_put(): decrements 1 from the reference count of the given
244		− instance. If the reference count reaches 0 then the given instance
245		− is freed
246		−
247		−The scsi_device structure has had reference counting infrastructure added.
248		−This effectively spreads the ownership of struct scsi_device instances
249		−across the various SCSI layers which use them. Previously such instances
250		−were exclusively owned by the mid level. See the access functions declared
251		−towards the end of include/scsi/scsi_device.h . If an LLD wants to keep
252		−a copy of a pointer to a scsi_device instance it should use scsi_device_get()
253		−to bump its reference count. When it is finished with the pointer it can
254		−use scsi_device_put() to decrement its reference count (and potentially
255		−delete it).
256		−
257		−^^ struct Scsi_Host actually has 2 reference counts which are manipulated
258		−in parallel by these functions.
259		−
260		−
261		−Conventions
262		−===========
263		−First, Linus Torvalds's thoughts on C coding style can be found in the
264		−Documentation/process/coding-style.rst file.
265		−
266		−Next, there is a movement to "outlaw" typedefs introducing synonyms for
267		−struct tags. Both can be still found in the SCSI subsystem, but
268		−the typedefs have been moved to a single file, scsi_typedefs.h to
269		−make their future removal easier, for example:
270		−"typedef struct scsi_cmnd Scsi_Cmnd;"
271		−
272		−Also, most C99 enhancements are encouraged to the extent they are supported
273		−by the relevant gcc compilers. So C99 style structure and array
274		−initializers are encouraged where appropriate. Don't go too far,
275		−VLAs are not properly supported yet. An exception to this is the use of
276		−"//" style comments; /.../ comments are still preferred in Linux.
277		−
278		−Well written, tested and documented code, need not be re-formatted to
279		−comply with the above conventions. For example, the aic7xxx driver
280		−comes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD
281		−and Adaptec have their own coding conventions.
282		−
283		−
284		−Mid level supplied functions
285		−============================
286		−These functions are supplied by the SCSI mid level for use by LLDs.
287		−The names (i.e. entry points) of these functions are exported
288		−so an LLD that is a module can access them. The kernel will
289		−arrange for the SCSI mid level to be loaded and initialized before any LLD
290		−is initialized. The functions below are listed alphabetically and their
291		−names all start with "scsi_".
292		−
293		−Summary:
294		− scsi_add_device - creates new scsi device (lu) instance
295		− scsi_add_host - perform sysfs registration and set up transport class
296		− scsi_change_queue_depth - change the queue depth on a SCSI device
297		− scsi_bios_ptable - return copy of block device's partition table
298		− scsi_block_requests - prevent further commands being queued to given host
299		− scsi_host_alloc - return a new scsi_host instance whose refcount==1
300		− scsi_host_get - increments Scsi_Host instance's refcount
301		− scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
302		− scsi_partsize - parse partition table into cylinders, heads + sectors
303		− scsi_register - create and register a scsi host adapter instance.
304		− scsi_remove_device - detach and remove a SCSI device
305		− scsi_remove_host - detach and remove all SCSI devices owned by host
306		− scsi_report_bus_reset - report scsi _bus_ reset observed
307		− scsi_scan_host - scan SCSI bus
308		− scsi_track_queue_full - track successive QUEUE_FULL events
309		− scsi_unblock_requests - allow further commands to be queued to given host
310		− scsi_unregister - [calls scsi_host_put()]
311		−
312		−
313		−Details:
314		−
315		−/**
316		− * scsi_add_device - creates new scsi device (lu) instance
317		− * @shost: pointer to scsi host instance
318		− * @channel: channel number (rarely other than 0)
319		− * @id: target id number
320		− * @lun: logical unit number
321		− *
322		− * Returns pointer to new struct scsi_device instance or
323		− * ERR_PTR(-ENODEV) (or some other bent pointer) if something is
324		− * wrong (e.g. no lu responds at given address)
325		− *
326		− * Might block: yes
327		− *
328		− * Notes: This call is usually performed internally during a scsi
329		− * bus scan when an HBA is added (i.e. scsi_scan_host()). So it
330		− * should only be called if the HBA becomes aware of a new scsi
331		− * device (lu) after scsi_scan_host() has completed. If successful
332		− * this call can lead to slave_alloc() and slave_configure() callbacks
333		− * into the LLD.
334		− *
335		− * Defined in: drivers/scsi/scsi_scan.c
336		− **/
337		−struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
338		− unsigned int channel,
339		− unsigned int id, unsigned int lun)
340		−
341		−
342		−/**
343		− * scsi_add_host - perform sysfs registration and set up transport class
344		− * @shost: pointer to scsi host instance
345		− * @dev: pointer to struct device of type scsi class
346		− *
347		− * Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
348		− *
349		− * Might block: no
350		− *
351		− * Notes: Only required in "hotplug initialization model" after a
352		− * successful call to scsi_host_alloc(). This function does not
353		− * scan the bus; this can be done by calling scsi_scan_host() or
354		− * in some other transport-specific way. The LLD must set up
355		− * the transport template before calling this function and may only
356		− * access the transport class data after this function has been called.
357		− *
358		− * Defined in: drivers/scsi/hosts.c
359		− **/
360		−int scsi_add_host(struct Scsi_Host shost, struct device dev)
361		−
362		−
363		−/**
364		− * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
365		− * @sdev: pointer to SCSI device to change queue depth on
366		− * @tags Number of tags allowed if tagged queuing enabled,
367		− * or number of commands the LLD can queue up
368		− * in non-tagged mode (as per cmd_per_lun).
369		− *
370		− * Returns nothing
371		− *
372		− * Might block: no
373		− *
374		− * Notes: Can be invoked any time on a SCSI device controlled by this
375		− * LLD. [Specifically during and after slave_configure() and prior to
376		− * slave_destroy().] Can safely be invoked from interrupt code.
377		− *
378		− * Defined in: drivers/scsi/scsi.c [see source code for more notes]
379		− *
380		− **/
381		−int scsi_change_queue_depth(struct scsi_device *sdev, int tags)
382		−
383		−
384		−/**
385		− * scsi_bios_ptable - return copy of block device's partition table
386		− * @dev: pointer to block device
387		− *
388		− * Returns pointer to partition table, or NULL for failure
389		− *
390		− * Might block: yes
391		− *
392		− * Notes: Caller owns memory returned (free with kfree() )
393		− *
394		− * Defined in: drivers/scsi/scsicam.c
395		− **/
396		−unsigned char scsi_bios_ptable(struct block_device dev)
397		−
398		−
399		−/**
400		− * scsi_block_requests - prevent further commands being queued to given host
401		− *
402		− * @shost: pointer to host to block commands on
403		− *
404		− * Returns nothing
405		− *
406		− * Might block: no
407		− *
408		− * Notes: There is no timer nor any other means by which the requests
409		− * get unblocked other than the LLD calling scsi_unblock_requests().
410		− *
411		− * Defined in: drivers/scsi/scsi_lib.c
412		−**/
413		−void scsi_block_requests(struct Scsi_Host * shost)
414		−
415		−
416		−/**
417		− * scsi_host_alloc - create a scsi host adapter instance and perform basic
418		− * initialization.
419		− * @sht: pointer to scsi host template
420		− * @privsize: extra bytes to allocate in hostdata array (which is the
421		− * last member of the returned Scsi_Host instance)
422		− *
423		− * Returns pointer to new Scsi_Host instance or NULL on failure
424		− *
425		− * Might block: yes
426		− *
427		− * Notes: When this call returns to the LLD, the SCSI bus scan on
428		− * this host has _not_ yet been done.
429		− * The hostdata array (by default zero length) is a per host scratch
430		− * area for the LLD's exclusive use.
431		− * Both associated refcounting objects have their refcount set to 1.
432		− * Full registration (in sysfs) and a bus scan are performed later when
433		− * scsi_add_host() and scsi_scan_host() are called.
434		− *
435		− * Defined in: drivers/scsi/hosts.c .
436		− **/
437		−struct Scsi_Host * scsi_host_alloc(struct scsi_host_template * sht,
438		− int privsize)
439		−
440		−
441		−/**
442		− * scsi_host_get - increment Scsi_Host instance refcount
443		− * @shost: pointer to struct Scsi_Host instance
444		− *
445		− * Returns nothing
446		− *
447		− * Might block: currently may block but may be changed to not block
448		− *
449		− * Notes: Actually increments the counts in two sub-objects
450		− *
451		− * Defined in: drivers/scsi/hosts.c
452		− **/
453		−void scsi_host_get(struct Scsi_Host *shost)
454		−
455		−
456		−/**
457		− * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
458		− * @shost: pointer to struct Scsi_Host instance
459		− *
460		− * Returns nothing
461		− *
462		− * Might block: currently may block but may be changed to not block
463		− *
464		− * Notes: Actually decrements the counts in two sub-objects. If the
465		− * latter refcount reaches 0, the Scsi_Host instance is freed.
466		− * The LLD need not worry exactly when the Scsi_Host instance is
467		− * freed, it just shouldn't access the instance after it has balanced
468		− * out its refcount usage.
469		− *
470		− * Defined in: drivers/scsi/hosts.c
471		− **/
472		−void scsi_host_put(struct Scsi_Host *shost)
473		−
474		−
475		−/**
476		− * scsi_partsize - parse partition table into cylinders, heads + sectors
477		− * @buf: pointer to partition table
478		− * @capacity: size of (total) disk in 512 byte sectors
479		− * @cyls: outputs number of cylinders calculated via this pointer
480		− * @hds: outputs number of heads calculated via this pointer
481		− * @secs: outputs number of sectors calculated via this pointer
482		− *
483		− * Returns 0 on success, -1 on failure
484		− *
485		− * Might block: no
486		− *
487		− * Notes: Caller owns memory returned (free with kfree() )
488		− *
489		− * Defined in: drivers/scsi/scsicam.c
490		− **/
491		−int scsi_partsize(unsigned char *buf, unsigned long capacity,
492		− unsigned int cyls, unsigned int hds, unsigned int *secs)
493		−
494		−
495		−/**
496		− * scsi_register - create and register a scsi host adapter instance.
497		− * @sht: pointer to scsi host template
498		− * @privsize: extra bytes to allocate in hostdata array (which is the
499		− * last member of the returned Scsi_Host instance)
500		− *
501		− * Returns pointer to new Scsi_Host instance or NULL on failure
502		− *
503		− * Might block: yes
504		− *
505		− * Notes: When this call returns to the LLD, the SCSI bus scan on
506		− * this host has _not_ yet been done.
507		− * The hostdata array (by default zero length) is a per host scratch
508		− * area for the LLD.
509		− *
510		− * Defined in: drivers/scsi/hosts.c .
511		− **/
512		−struct Scsi_Host * scsi_register(struct scsi_host_template * sht,
513		− int privsize)
514		−
515		−
516		−/**
517		− * scsi_remove_device - detach and remove a SCSI device
518		− * @sdev: a pointer to a scsi device instance
519		− *
520		− * Returns value: 0 on success, -EINVAL if device not attached
521		− *
522		− * Might block: yes
523		− *
524		− * Notes: If an LLD becomes aware that a scsi device (lu) has
525		− * been removed but its host is still present then it can request
526		− * the removal of that scsi device. If successful this call will
527		− * lead to the slave_destroy() callback being invoked. sdev is an
528		− * invalid pointer after this call.
529		− *
530		− * Defined in: drivers/scsi/scsi_sysfs.c .
531		− **/
532		−int scsi_remove_device(struct scsi_device *sdev)
533		−
534		−
535		−/**
536		− * scsi_remove_host - detach and remove all SCSI devices owned by host
537		− * @shost: a pointer to a scsi host instance
538		− *
539		− * Returns value: 0 on success, 1 on failure (e.g. LLD busy ??)
540		− *
541		− * Might block: yes
542		− *
543		− * Notes: Should only be invoked if the "hotplug initialization
544		− * model" is being used. It should be called _prior_ to
545		− * scsi_unregister().
546		− *
547		− * Defined in: drivers/scsi/hosts.c .
548		− **/
549		−int scsi_remove_host(struct Scsi_Host *shost)
550		−
551		−
552		−/**
553		− * scsi_report_bus_reset - report scsi _bus_ reset observed
554		− * @shost: a pointer to a scsi host involved
555		− * @channel: channel (within) host on which scsi bus reset occurred
556		− *
557		− * Returns nothing
558		− *
559		− * Might block: no
560		− *
561		− * Notes: This only needs to be called if the reset is one which
562		− * originates from an unknown location. Resets originated by the
563		− * mid level itself don't need to call this, but there should be
564		− * no harm. The main purpose of this is to make sure that a
565		− * CHECK_CONDITION is properly treated.
566		− *
567		− * Defined in: drivers/scsi/scsi_error.c .
568		− **/
569		−void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
570		−
571		−
572		−/**
573		− * scsi_scan_host - scan SCSI bus
574		− * @shost: a pointer to a scsi host instance
575		− *
576		− * Might block: yes
577		− *
578		− * Notes: Should be called after scsi_add_host()
579		− *
580		− * Defined in: drivers/scsi/scsi_scan.c
581		− **/
582		−void scsi_scan_host(struct Scsi_Host *shost)
583		−
584		−
585		−/**
586		− * scsi_track_queue_full - track successive QUEUE_FULL events on given
587		− * device to determine if and when there is a need
588		− * to adjust the queue depth on the device.
589		− * @sdev: pointer to SCSI device instance
590		− * @depth: Current number of outstanding SCSI commands on this device,
591		− * not counting the one returned as QUEUE_FULL.
592		− *
593		− * Returns 0 - no change needed
594		− * >0 - adjust queue depth to this new depth
595		− * -1 - drop back to untagged operation using host->cmd_per_lun
596		− * as the untagged command depth
597		− *
598		− * Might block: no
599		− *
600		− * Notes: LLDs may call this at any time and we will do "The Right
601		− * Thing"; interrupt context safe.
602		− *
603		− * Defined in: drivers/scsi/scsi.c .
604		− **/
605		−int scsi_track_queue_full(struct scsi_device *sdev, int depth)
606		−
607		−
608		−/**
609		− * scsi_unblock_requests - allow further commands to be queued to given host
610		− *
611		− * @shost: pointer to host to unblock commands on
612		− *
613		− * Returns nothing
614		− *
615		− * Might block: no
616		− *
617		− * Defined in: drivers/scsi/scsi_lib.c .
618		−**/
619		−void scsi_unblock_requests(struct Scsi_Host * shost)
620		−
621		−
622		−/**
623		− * scsi_unregister - unregister and free memory used by host instance
624		− * @shp: pointer to scsi host instance to unregister.
625		− *
626		− * Returns nothing
627		− *
628		− * Might block: no
629		− *
630		− * Notes: Should not be invoked if the "hotplug initialization
631		− * model" is being used. Called internally by exit_this_scsi_driver()
632		− * in the "passive initialization model". Hence a LLD has no need to
633		− * call this function directly.
634		− *
635		− * Defined in: drivers/scsi/hosts.c .
636		− **/
637		−void scsi_unregister(struct Scsi_Host * shp)
638		−
639		−
640		−
641		−
642		−Interface Functions
643		−===================
644		−Interface functions are supplied (defined) by LLDs and their function
645		−pointers are placed in an instance of struct scsi_host_template which
646		−is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()].
647		−Some are mandatory. Interface functions should be declared static. The
648		−accepted convention is that driver "xyz" will declare its slave_configure()
649		−function as:
650		− static int xyz_slave_configure(struct scsi_device * sdev);
651		−and so forth for all interface functions listed below.
652		−
653		−A pointer to this function should be placed in the 'slave_configure' member
654		−of a "struct scsi_host_template" instance. A pointer to such an instance
655		−should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
656		−init_this_scsi_driver()].
657		−
658		−The interface functions are also described in the include/scsi/scsi_host.h
659		−file immediately above their definition point in "struct scsi_host_template".
660		−In some cases more detail is given in scsi_host.h than below.
661		−
662		−The interface functions are listed below in alphabetical order.
663		−
664		−Summary:
665		− bios_param - fetch head, sector, cylinder info for a disk
666		− eh_timed_out - notify the host that a command timer expired
667		− eh_abort_handler - abort given command
668		− eh_bus_reset_handler - issue SCSI bus reset
669		− eh_device_reset_handler - issue SCSI device reset
670		− eh_host_reset_handler - reset host (host bus adapter)
671		− info - supply information about given host
672		− ioctl - driver can respond to ioctls
673		− proc_info - supports /proc/scsi/{driver_name}/{host_no}
674		− queuecommand - queue scsi command, invoke 'done' on completion
675		− slave_alloc - prior to any commands being sent to a new device
676		− slave_configure - driver fine tuning for given device after attach
677		− slave_destroy - given device is about to be shut down
678		−
679		−
680		−Details:
681		−
682		−/**
683		− * bios_param - fetch head, sector, cylinder info for a disk
684		− * @sdev: pointer to scsi device context (defined in
685		− * include/scsi/scsi_device.h)
686		− * @bdev: pointer to block device context (defined in fs.h)
687		− * @capacity: device size (in 512 byte sectors)
688		− * @params: three element array to place output:
689		− * params[0] number of heads (max 255)
690		− * params[1] number of sectors (max 63)
691		− * params[2] number of cylinders
692		− *
693		− * Return value is ignored
694		− *
695		− * Locks: none
696		− *
697		− * Calling context: process (sd)
698		− *
699		− * Notes: an arbitrary geometry (based on READ CAPACITY) is used
700		− * if this function is not provided. The params array is
701		− * pre-initialized with made up values just in case this function
702		− * doesn't output anything.
703		− *
704		− * Optionally defined in: LLD
705		− **/
706		− int bios_param(struct scsi_device * sdev, struct block_device *bdev,
707		− sector_t capacity, int params[3])
708		−
709		−
710		−/**
711		− * eh_timed_out - The timer for the command has just fired
712		− * @scp: identifies command timing out
713		− *
714		− * Returns:
715		− *
716		− * EH_HANDLED: I fixed the error, please complete the command
717		− * EH_RESET_TIMER: I need more time, reset the timer and
718		− * begin counting again
719		− * EH_NOT_HANDLED Begin normal error recovery
720		− *
721		− *
722		− * Locks: None held
723		− *
724		− * Calling context: interrupt
725		− *
726		− * Notes: This is to give the LLD an opportunity to do local recovery.
727		− * This recovery is limited to determining if the outstanding command
728		− * will ever complete. You may not abort and restart the command from
729		− * this callback.
730		− *
731		− * Optionally defined in: LLD
732		− **/
733		− int eh_timed_out(struct scsi_cmnd * scp)
734		−
735		−
736		−/**
737		− * eh_abort_handler - abort command associated with scp
738		− * @scp: identifies command to be aborted
739		− *
740		− * Returns SUCCESS if command aborted else FAILED
741		− *
742		− * Locks: None held
743		− *
744		− * Calling context: kernel thread
745		− *
746		− * Notes: If 'no_async_abort' is defined this callback
747		− * will be invoked from scsi_eh thread. No other commands
748		− * will then be queued on current host during eh.
749		− * Otherwise it will be called whenever scsi_times_out()
750		− * is called due to a command timeout.
751		− *
752		− * Optionally defined in: LLD
753		− **/
754		− int eh_abort_handler(struct scsi_cmnd * scp)
755		−
756		−
757		−/**
758		− * eh_bus_reset_handler - issue SCSI bus reset
759		− * @scp: SCSI bus that contains this device should be reset
760		− *
761		− * Returns SUCCESS if command aborted else FAILED
762		− *
763		− * Locks: None held
764		− *
765		− * Calling context: kernel thread
766		− *
767		− * Notes: Invoked from scsi_eh thread. No other commands will be
768		− * queued on current host during eh.
769		− *
770		− * Optionally defined in: LLD
771		− **/
772		− int eh_bus_reset_handler(struct scsi_cmnd * scp)
773		−
774		−
775		−/**
776		− * eh_device_reset_handler - issue SCSI device reset
777		− * @scp: identifies SCSI device to be reset
778		− *
779		− * Returns SUCCESS if command aborted else FAILED
780		− *
781		− * Locks: None held
782		− *
783		− * Calling context: kernel thread
784		− *
785		− * Notes: Invoked from scsi_eh thread. No other commands will be
786		− * queued on current host during eh.
787		− *
788		− * Optionally defined in: LLD
789		− **/
790		− int eh_device_reset_handler(struct scsi_cmnd * scp)
791		−
792		−
793		−/**
794		− * eh_host_reset_handler - reset host (host bus adapter)
795		− * @scp: SCSI host that contains this device should be reset
796		− *
797		− * Returns SUCCESS if command aborted else FAILED
798		− *
799		− * Locks: None held
800		− *
801		− * Calling context: kernel thread
802		− *
803		− * Notes: Invoked from scsi_eh thread. No other commands will be
804		− * queued on current host during eh.
805		− * With the default eh_strategy in place, if none of the _abort_,
806		− * _device_reset_, _bus_reset_ or this eh handler function are
807		− * defined (or they all return FAILED) then the device in question
808		− * will be set offline whenever eh is invoked.
809		− *
810		− * Optionally defined in: LLD
811		− **/
812		− int eh_host_reset_handler(struct scsi_cmnd * scp)
813		−
814		−
815		−/**
816		− * info - supply information about given host: driver name plus data
817		− * to distinguish given host
818		− * @shp: host to supply information about
819		− *
820		− * Return ASCII null terminated string. [This driver is assumed to
821		− * manage the memory pointed to and maintain it, typically for the
822		− * lifetime of this host.]
823		− *
824		− * Locks: none
825		− *
826		− * Calling context: process
827		− *
828		− * Notes: Often supplies PCI or ISA information such as IO addresses
829		− * and interrupt numbers. If not supplied struct Scsi_Host::name used
830		− * instead. It is assumed the returned information fits on one line
831		− * (i.e. does not included embedded newlines).
832		− * The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this
833		− * function (or struct Scsi_Host::name if this function is not
834		− * available).
835		− * In a similar manner, init_this_scsi_driver() outputs to the console
836		− * each host's "info" (or name) for the driver it is registering.
837		− * Also if proc_info() is not supplied, the output of this function
838		− * is used instead.
839		− *
840		− * Optionally defined in: LLD
841		− **/
842		− const char * info(struct Scsi_Host * shp)
843		−
844		−
845		−/**
846		− * ioctl - driver can respond to ioctls
847		− * @sdp: device that ioctl was issued for
848		− * @cmd: ioctl number
849		− * @arg: pointer to read or write data from. Since it points to
850		− * user space, should use appropriate kernel functions
851		− * (e.g. copy_from_user() ). In the Unix style this argument
852		− * can also be viewed as an unsigned long.
853		− *
854		− * Returns negative "errno" value when there is a problem. 0 or a
855		− * positive value indicates success and is returned to the user space.
856		− *
857		− * Locks: none
858		− *
859		− * Calling context: process
860		− *
861		− * Notes: The SCSI subsystem uses a "trickle down" ioctl model.
862		− * The user issues an ioctl() against an upper level driver
863		− * (e.g. /dev/sdc) and if the upper level driver doesn't recognize
864		− * the 'cmd' then it is passed to the SCSI mid level. If the SCSI
865		− * mid level does not recognize it, then the LLD that controls
866		− * the device receives the ioctl. According to recent Unix standards
867		− * unsupported ioctl() 'cmd' numbers should return -ENOTTY.
868		− *
869		− * Optionally defined in: LLD
870		− **/
871		− int ioctl(struct scsi_device sdp, int cmd, void arg)
872		−
873		−
874		−/**
875		− * proc_info - supports /proc/scsi/{driver_name}/{host_no}
876		− * @buffer: anchor point to output to (0==writeto1_read0) or fetch from
877		− * (1==writeto1_read0).
878		− * @start: where "interesting" data is written to. Ignored when
879		− * 1==writeto1_read0.
880		− * @offset: offset within buffer 0==writeto1_read0 is actually
881		− * interested in. Ignored when 1==writeto1_read0 .
882		− * @length: maximum (or actual) extent of buffer
883		− * @host_no: host number of interest (struct Scsi_Host::host_no)
884		− * @writeto1_read0: 1 -> data coming from user space towards driver
885		− * (e.g. "echo some_string > /proc/scsi/xyz/2")
886		− * 0 -> user what data from this driver
887		− * (e.g. "cat /proc/scsi/xyz/2")
888		− *
889		− * Returns length when 1==writeto1_read0. Otherwise number of chars
890		− * output to buffer past offset.
891		− *
892		− * Locks: none held
893		− *
894		− * Calling context: process
895		− *
896		− * Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs
897		− * support can now be configured out of the scsi subsystem.
898		− *
899		− * Optionally defined in: LLD
900		− **/
901		− int proc_info(char * buffer, char ** start, off_t offset,
902		− int length, int host_no, int writeto1_read0)
903		−
904		−
905		−/**
906		− * queuecommand - queue scsi command, invoke scp->scsi_done on completion
907		− * @shost: pointer to the scsi host object
908		− * @scp: pointer to scsi command object
909		− *
910		− * Returns 0 on success.
911		− *
912		− * If there's a failure, return either:
913		− *
914		− * SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
915		− * SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full
916		− *
917		− * On both of these returns, the mid-layer will requeue the I/O
918		− *
919		− * - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
920		− * device will be paused, and it will be unpaused when a command to
921		− * the device returns (or after a brief delay if there are no more
922		− * outstanding commands to it). Commands to other devices continue
923		− * to be processed normally.
924		− *
925		− * - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
926		− * is paused and will be unpaused when any command returns from
927		− * the host (or after a brief delay if there are no outstanding
928		− * commands to the host).
929		− *
930		− * For compatibility with earlier versions of queuecommand, any
931		− * other return value is treated the same as
932		− * SCSI_MLQUEUE_HOST_BUSY.
933		− *
934		− * Other types of errors that are detected immediately may be
935		− * flagged by setting scp->result to an appropriate value,
936		− * invoking the scp->scsi_done callback, and then returning 0
937		− * from this function. If the command is not performed
938		− * immediately (and the LLD is starting (or will start) the given
939		− * command) then this function should place 0 in scp->result and
940		− * return 0.
941		− *
942		− * Command ownership. If the driver returns zero, it owns the
943		− * command and must take responsibility for ensuring the
944		− * scp->scsi_done callback is executed. Note: the driver may
945		− * call scp->scsi_done before returning zero, but after it has
946		− * called scp->scsi_done, it may not return any value other than
947		− * zero. If the driver makes a non-zero return, it must not
948		− * execute the command's scsi_done callback at any time.
949		− *
950		− * Locks: up to and including 2.6.36, struct Scsi_Host::host_lock
951		− * held on entry (with "irqsave") and is expected to be
952		− * held on return. From 2.6.37 onwards, queuecommand is
953		− * called without any locks held.
954		− *
955		− * Calling context: in interrupt (soft irq) or process context
956		− *
957		− * Notes: This function should be relatively fast. Normally it
958		− * will not wait for IO to complete. Hence the scp->scsi_done
959		− * callback is invoked (often directly from an interrupt service
960		− * routine) some time after this function has returned. In some
961		− * cases (e.g. pseudo adapter drivers that manufacture the
962		− * response to a SCSI INQUIRY) the scp->scsi_done callback may be
963		− * invoked before this function returns. If the scp->scsi_done
964		− * callback is not invoked within a certain period the SCSI mid
965		− * level will commence error processing. If a status of CHECK
966		− * CONDITION is placed in "result" when the scp->scsi_done
967		− * callback is invoked, then the LLD driver should perform
968		− * autosense and fill in the struct scsi_cmnd::sense_buffer
969		− * array. The scsi_cmnd::sense_buffer array is zeroed prior to
970		− * the mid level queuing a command to an LLD.
971		− *
972		− * Defined in: LLD
973		− **/
974		− int queuecommand(struct Scsi_Host shost, struct scsi_cmnd scp)
975		−
976		−
977		−/**
978		− * slave_alloc - prior to any commands being sent to a new device
979		− * (i.e. just prior to scan) this call is made
980		− * @sdp: pointer to new device (about to be scanned)
981		− *
982		− * Returns 0 if ok. Any other return is assumed to be an error and
983		− * the device is ignored.
984		− *
985		− * Locks: none
986		− *
987		− * Calling context: process
988		− *
989		− * Notes: Allows the driver to allocate any resources for a device
990		− * prior to its initial scan. The corresponding scsi device may not
991		− * exist but the mid level is just about to scan for it (i.e. send
992		− * and INQUIRY command plus ...). If a device is found then
993		− * slave_configure() will be called while if a device is not found
994		− * slave_destroy() is called.
995		− * For more details see the include/scsi/scsi_host.h file.
996		− *
997		− * Optionally defined in: LLD
998		− **/
999		− int slave_alloc(struct scsi_device *sdp)
1000		−
1001		−
1002		−/**
1003		− * slave_configure - driver fine tuning for given device just after it
1004		− * has been first scanned (i.e. it responded to an
1005		− * INQUIRY)
1006		− * @sdp: device that has just been attached
1007		− *
1008		− * Returns 0 if ok. Any other return is assumed to be an error and
1009		− * the device is taken offline. [offline devices will _not_ have
1010		− * slave_destroy() called on them so clean up resources.]
1011		− *
1012		− * Locks: none
1013		− *
1014		− * Calling context: process
1015		− *
1016		− * Notes: Allows the driver to inspect the response to the initial
1017		− * INQUIRY done by the scanning code and take appropriate action.
1018		− * For more details see the include/scsi/scsi_host.h file.
1019		− *
1020		− * Optionally defined in: LLD
1021		− **/
1022		− int slave_configure(struct scsi_device *sdp)
1023		−
1024		−
1025		−/**
1026		− * slave_destroy - given device is about to be shut down. All
1027		− * activity has ceased on this device.
1028		− * @sdp: device that is about to be shut down
1029		− *
1030		− * Returns nothing
1031		− *
1032		− * Locks: none
1033		− *
1034		− * Calling context: process
1035		− *
1036		− * Notes: Mid level structures for given device are still in place
1037		− * but are about to be torn down. Any per device resources allocated
1038		− * by this driver for given device should be freed now. No further
1039		− * commands will be sent for this sdp instance. [However the device
1040		− * could be re-attached in the future in which case a new instance
1041		− * of struct scsi_device would be supplied by future slave_alloc()
1042		− * and slave_configure() calls.]
1043		− *
1044		− * Optionally defined in: LLD
1045		− **/
1046		− void slave_destroy(struct scsi_device *sdp)
1047		−
1048		−
1049		−
1050		−Data Structures
1051		−===============
1052		−struct scsi_host_template
1053		−-------------------------
1054		−There is one "struct scsi_host_template" instance per LLD ***. It is
1055		−typically initialized as a file scope static in a driver's header file. That
1056		−way members that are not explicitly initialized will be set to 0 or NULL.
1057		−Member of interest:
1058		− name - name of driver (may contain spaces, please limit to
1059		− less than 80 characters)
1060		− proc_name - name used in "/proc/scsi/<proc_name>/<host_no>" and
1061		− by sysfs in one of its "drivers" directories. Hence
1062		− "proc_name" should only contain characters acceptable
1063		− to a Unix file name.
1064		− (*queuecommand)() - primary callback that the mid level uses to inject
1065		− SCSI commands into an LLD.
1066		−The structure is defined and commented in include/scsi/scsi_host.h
1067		−
1068		−*** In extreme situations a single driver may have several instances
1069		− if it controls several different classes of hardware (e.g. an LLD
1070		− that handles both ISA and PCI cards and has a separate instance of
1071		− struct scsi_host_template for each class).
1072		−
1073		−struct Scsi_Host
1074		−----------------
1075		−There is one struct Scsi_Host instance per host (HBA) that an LLD
1076		−controls. The struct Scsi_Host structure has many members in common
1077		−with "struct scsi_host_template". When a new struct Scsi_Host instance
1078		−is created (in scsi_host_alloc() in hosts.c) those common members are
1079		−initialized from the driver's struct scsi_host_template instance. Members
1080		−of interest:
1081		− host_no - system wide unique number that is used for identifying
1082		− this host. Issued in ascending order from 0.
1083		− can_queue - must be greater than 0; do not send more than can_queue
1084		− commands to the adapter.
1085		− this_id - scsi id of host (scsi initiator) or -1 if not known
1086		− sg_tablesize - maximum scatter gather elements allowed by host.
1087		− Set this to SG_ALL or less to avoid chained SG lists.
1088		− Must be at least 1.
1089		− max_sectors - maximum number of sectors (usually 512 bytes) allowed
1090		− in a single SCSI command. The default value of 0 leads
1091		− to a setting of SCSI_DEFAULT_MAX_SECTORS (defined in
1092		− scsi_host.h) which is currently set to 1024. So for a
1093		− disk the maximum transfer size is 512 KB when max_sectors
1094		− is not defined. Note that this size may not be sufficient
1095		− for disk firmware uploads.
1096		− cmd_per_lun - maximum number of commands that can be queued on devices
1097		− controlled by the host. Overridden by LLD calls to
1098		− scsi_change_queue_depth().
1099		− unchecked_isa_dma - 1=>only use bottom 16 MB of ram (ISA DMA addressing
1100		− restriction), 0=>can use full 32 bit (or better) DMA
1101		− address space
1102		− no_async_abort - 1=>Asynchronous aborts are not supported
1103		− 0=>Timed-out commands will be aborted asynchronously
1104		− hostt - pointer to driver's struct scsi_host_template from which
1105		− this struct Scsi_Host instance was spawned
1106		− hostt->proc_name - name of LLD. This is the driver name that sysfs uses
1107		− transportt - pointer to driver's struct scsi_transport_template instance
1108		− (if any). FC and SPI transports currently supported.
1109		− sh_list - a double linked list of pointers to all struct Scsi_Host
1110		− instances (currently ordered by ascending host_no)
1111		− my_devices - a double linked list of pointers to struct scsi_device
1112		− instances that belong to this host.
1113		− hostdata[0] - area reserved for LLD at end of struct Scsi_Host. Size
1114		− is set by the second argument (named 'xtr_bytes') to
1115		− scsi_host_alloc() or scsi_register().
1116		− vendor_id - a unique value that identifies the vendor supplying
1117		− the LLD for the Scsi_Host. Used most often in validating
1118		− vendor-specific message requests. Value consists of an
1119		− identifier type and a vendor-specific value.
1120		− See scsi_netlink.h for a description of valid formats.
1121		−
1122		−The scsi_host structure is defined in include/scsi/scsi_host.h
1123		−
1124		−struct scsi_device
1125		−------------------
1126		−Generally, there is one instance of this structure for each SCSI logical unit
1127		−on a host. Scsi devices connected to a host are uniquely identified by a
1128		−channel number, target id and logical unit number (lun).
1129		−The structure is defined in include/scsi/scsi_device.h
1130		−
1131		−struct scsi_cmnd
1132		−----------------
1133		−Instances of this structure convey SCSI commands to the LLD and responses
1134		−back to the mid level. The SCSI mid level will ensure that no more SCSI
1135		−commands become queued against the LLD than are indicated by
1136		−scsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will
1137		−be at least one instance of struct scsi_cmnd available for each SCSI device.
1138		−Members of interest:
1139		− cmnd - array containing SCSI command
1140		− cmnd_len - length (in bytes) of SCSI command
1141		− sc_data_direction - direction of data transfer in data phase. See
1142		− "enum dma_data_direction" in include/linux/dma-mapping.h
1143		− request_bufflen - number of data bytes to transfer (0 if no data phase)
1144		− use_sg - ==0 -> no scatter gather list, hence transfer data
1145		− to/from request_buffer
1146		− - >0 -> scatter gather list (actually an array) in
1147		− request_buffer with use_sg elements
1148		− request_buffer - either contains data buffer or scatter gather list
1149		− depending on the setting of use_sg. Scatter gather
1150		− elements are defined by 'struct scatterlist' found
1151		− in include/linux/scatterlist.h .
1152		− done - function pointer that should be invoked by LLD when the
1153		− SCSI command is completed (successfully or otherwise).
1154		− Should only be called by an LLD if the LLD has accepted
1155		− the command (i.e. queuecommand() returned or will return
1156		− 0). The LLD may invoke 'done' prior to queuecommand()
1157		− finishing.
1158		− result - should be set by LLD prior to calling 'done'. A value
1159		− of 0 implies a successfully completed command (and all
1160		− data (if any) has been transferred to or from the SCSI
1161		− target device). 'result' is a 32 bit unsigned integer that
1162		− can be viewed as 4 related bytes. The SCSI status value is
1163		− in the LSB. See include/scsi/scsi.h status_byte(),
1164		− msg_byte(), host_byte() and driver_byte() macros and
1165		− related constants.
1166		− sense_buffer - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
1167		− should be written when the SCSI status (LSB of 'result')
1168		− is set to CHECK_CONDITION (2). When CHECK_CONDITION is
1169		− set, if the top nibble of sense_buffer[0] has the value 7
1170		− then the mid level will assume the sense_buffer array
1171		− contains a valid SCSI sense buffer; otherwise the mid
1172		− level will issue a REQUEST_SENSE SCSI command to
1173		− retrieve the sense buffer. The latter strategy is error
1174		− prone in the presence of command queuing so the LLD should
1175		− always "auto-sense".
1176		− device - pointer to scsi_device object that this command is
1177		− associated with.
1178		− resid - an LLD should set this signed integer to the requested
1179		− transfer length (i.e. 'request_bufflen') less the number
1180		− of bytes that are actually transferred. 'resid' is
1181		− preset to 0 so an LLD can ignore it if it cannot detect
1182		− underruns (overruns should be rare). If possible an LLD
1183		− should set 'resid' prior to invoking 'done'. The most
1184		− interesting case is data transfers from a SCSI target
1185		− device (e.g. READs) that underrun.
1186		− underflow - LLD should place (DID_ERROR << 16) in 'result' if
1187		− actual number of bytes transferred is less than this
1188		− figure. Not many LLDs implement this check and some that
1189		− do just output an error message to the log rather than
1190		− report a DID_ERROR. Better for an LLD to implement
1191		− 'resid'.
1192		−
1193		−It is recommended that a LLD set 'resid' on data transfers from a SCSI
1194		−target device (e.g. READs). It is especially important that 'resid' is set
1195		−when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR
1196		−(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much
1197		−data has been received then the safest approach is to indicate no bytes have
1198		−been received. For example: to indicate that no valid data has been received
1199		−a LLD might use these helpers:
1200		− scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
1201		−where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512
1202		−bytes blocks has been received 'resid' could be set like this:
1203		− scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
1204		−
1205		−The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h
1206		−
1207		−
1208		−Locks
1209		−=====
1210		−Each struct Scsi_Host instance has a spin_lock called struct
1211		−Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in
1212		−hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
1213		−is initialized to point at default_lock. Thereafter lock and unlock
1214		−operations performed by the mid level use the struct Scsi_Host::host_lock
1215		−pointer. Previously drivers could override the host_lock pointer but
1216		−this is not allowed anymore.
1217		−
1218		−
1219		−Autosense
1220		−=========
1221		−Autosense (or auto-sense) is defined in the SAM-2 document as "the
1222		−automatic return of sense data to the application client coincident
1223		−with the completion of a SCSI command" when a status of CHECK CONDITION
1224		−occurs. LLDs should perform autosense. This should be done when the LLD
1225		−detects a CHECK CONDITION status by either:
1226		− a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
1227		− to perform an extra data in phase on such responses
1228		− b) or, the LLD issuing a REQUEST SENSE command itself
1229		−
1230		−Either way, when a status of CHECK CONDITION is detected, the mid level
1231		−decides whether the LLD has performed autosense by checking struct
1232		−scsi_cmnd::sense_buffer[0] . If this byte has an upper nibble of 7 (or 0xf)
1233		−then autosense is assumed to have taken place. If it has another value (and
1234		−this byte is initialized to 0 before each command) then the mid level will
1235		−issue a REQUEST SENSE command.
1236		−
1237		−In the presence of queued commands the "nexus" that maintains sense
1238		−buffer data from the command that failed until a following REQUEST SENSE
1239		−may get out of synchronization. This is why it is best for the LLD
1240		−to perform autosense.
1241		−
1242		−
1243		−Changes since lk 2.4 series
1244		−===========================
1245		−io_request_lock has been replaced by several finer grained locks. The lock
1246		−relevant to LLDs is struct Scsi_Host::host_lock and there is
1247		−one per SCSI host.
1248		−
1249		−The older error handling mechanism has been removed. This means the
1250		−LLD interface functions abort() and reset() have been removed.
1251		−The struct scsi_host_template::use_new_eh_code flag has been removed.
1252		−
1253		−In the 2.4 series the SCSI subsystem configuration descriptions were
1254		−aggregated with the configuration descriptions from all other Linux
1255		−subsystems in the Documentation/Configure.help file. In the 2.6 series,
1256		−the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig
1257		−file that contains both configuration and help information.
1258		−
1259		−struct SHT has been renamed to struct scsi_host_template.
1260		−
1261		−Addition of the "hotplug initialization model" and many extra functions
1262		−to support it.
1263		−
1264		−
1265		−Credits
1266		−=======
1267		−The following people have contributed to this document:
1268		− Mike Anderson <andmike at us dot ibm dot com>
1269		− James Bottomley <James dot Bottomley at hansenpartnership dot com>
1270		− Patrick Mansfield <patmans at us dot ibm dot com>
1271		− Christoph Hellwig <hch at infradead dot org>
1272		− Doug Ledford <dledford at redhat dot com>
1273		− Andries Brouwer <Andries dot Brouwer at cwi dot nl>
1274		− Randy Dunlap <rdunlap at xenotime dot net>
1275		− Alan Stern <stern at rowland dot harvard dot edu>
1276		−
1277		−
1278		−Douglas Gilbert
1279		−dgilbert at interlog dot com
1280		−21st September 2004

scripts/documentation-file-ref-check+1−1

@@ -12,7 +12,7 @@ use Getopt::Long qw(:config no_auto_abbrev); · 11 unmodified lines
12	12	# to mention a past documentation file, for example, to give credits for
13	13	# the original work.
14	14	my %false_positives = (
15		− "Documentation/scsi/scsi_mid_low_api.txt" => "Documentation/Configure.help",
	15	+ "Documentation/scsi/scsi_mid_low_api.rst" => "Documentation/Configure.help",
16	16	"drivers/vhost/vhost.c" => "Documentation/virtual/lguest/lguest.c",
17	17	);
18	18