Contents of /alx-src/trunk/kernel26-alx/linux/Documentation/DocBook/scsidrivers.tmpl
Parent Directory | Revision Log
Revision 628 -
(show annotations)
(download)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 6706 byte(s)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 6706 byte(s)
import linux sources based on 2.6.12-alx-r9: -using linux-2.6.12.6 -using 2.6.12-ck6 patch set -using fbsplash-0.9.2-r3 -using vesafb-tng-0.9-rc7 -using squashfs-2.2 -added cddvd-cmdfilter-drop.patch as ck dropped it -added via-epia-dri (cle266) patch -added zd1211-svn-32 wlan driver (http://zd1211.ath.cx/download/) -added debian patches to zd1211 for wep256 etc
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
4 | |
5 | <book id="scsidrivers"> |
6 | <bookinfo> |
7 | <title>SCSI Subsystem Interfaces</title> |
8 | |
9 | <authorgroup> |
10 | <author> |
11 | <firstname>Douglas</firstname> |
12 | <surname>Gilbert</surname> |
13 | <affiliation> |
14 | <address> |
15 | <email>dgilbert@interlog.com</email> |
16 | </address> |
17 | </affiliation> |
18 | </author> |
19 | </authorgroup> |
20 | <pubdate>2003-08-11</pubdate> |
21 | |
22 | <copyright> |
23 | <year>2002</year> |
24 | <year>2003</year> |
25 | <holder>Douglas Gilbert</holder> |
26 | </copyright> |
27 | |
28 | <legalnotice> |
29 | <para> |
30 | This documentation is free software; you can redistribute |
31 | it and/or modify it under the terms of the GNU General Public |
32 | License as published by the Free Software Foundation; either |
33 | version 2 of the License, or (at your option) any later |
34 | version. |
35 | </para> |
36 | |
37 | <para> |
38 | This program is distributed in the hope that it will be |
39 | useful, but WITHOUT ANY WARRANTY; without even the implied |
40 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
41 | See the GNU General Public License for more details. |
42 | </para> |
43 | |
44 | <para> |
45 | You should have received a copy of the GNU General Public |
46 | License along with this program; if not, write to the Free |
47 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
48 | MA 02111-1307 USA |
49 | </para> |
50 | |
51 | <para> |
52 | For more details see the file COPYING in the source |
53 | distribution of Linux. |
54 | </para> |
55 | </legalnotice> |
56 | |
57 | </bookinfo> |
58 | |
59 | <toc></toc> |
60 | |
61 | <chapter id="intro"> |
62 | <title>Introduction</title> |
63 | <para> |
64 | This document outlines the interface between the Linux scsi mid level |
65 | and lower level drivers. Lower level drivers are variously called HBA |
66 | (host bus adapter) drivers, host drivers (HD) or pseudo adapter drivers. |
67 | The latter alludes to the fact that a lower level driver may be a |
68 | bridge to another IO subsystem (and the "ide-scsi" driver is an example |
69 | of this). There can be many lower level drivers active in a running |
70 | system, but only one per hardware type. For example, the aic7xxx driver |
71 | controls adaptec controllers based on the 7xxx chip series. Most lower |
72 | level drivers can control one or more scsi hosts (a.k.a. scsi initiators). |
73 | </para> |
74 | <para> |
75 | This document can been found in an ASCII text file in the linux kernel |
76 | source: <filename>Documentation/scsi/scsi_mid_low_api.txt</filename> . |
77 | It currently hold a little more information than this document. The |
78 | <filename>drivers/scsi/hosts.h</filename> and <filename> |
79 | drivers/scsi/scsi.h</filename> headers contain descriptions of members |
80 | of important structures for the scsi subsystem. |
81 | </para> |
82 | </chapter> |
83 | |
84 | <chapter id="driver-struct"> |
85 | <title>Driver structure</title> |
86 | <para> |
87 | Traditionally a lower level driver for the scsi subsystem has been |
88 | at least two files in the drivers/scsi directory. For example, a |
89 | driver called "xyz" has a header file "xyz.h" and a source file |
90 | "xyz.c". [Actually there is no good reason why this couldn't all |
91 | be in one file.] Some drivers that have been ported to several operating |
92 | systems (e.g. aic7xxx which has separate files for generic and |
93 | OS-specific code) have more than two files. Such drivers tend to have |
94 | their own directory under the drivers/scsi directory. |
95 | </para> |
96 | <para> |
97 | scsi_module.c is normally included at the end of a lower |
98 | level driver. For it to work a declaration like this is needed before |
99 | it is included: |
100 | <programlisting> |
101 | static Scsi_Host_Template driver_template = DRIVER_TEMPLATE; |
102 | /* DRIVER_TEMPLATE should contain pointers to supported interface |
103 | functions. Scsi_Host_Template is defined hosts.h */ |
104 | #include "scsi_module.c" |
105 | </programlisting> |
106 | </para> |
107 | <para> |
108 | The scsi_module.c assumes the name "driver_template" is appropriately |
109 | defined. It contains 2 functions: |
110 | <orderedlist> |
111 | <listitem><para> |
112 | init_this_scsi_driver() called during builtin and module driver |
113 | initialization: invokes mid level's scsi_register_host() |
114 | </para></listitem> |
115 | <listitem><para> |
116 | exit_this_scsi_driver() called during closedown: invokes |
117 | mid level's scsi_unregister_host() |
118 | </para></listitem> |
119 | </orderedlist> |
120 | </para> |
121 | <para> |
122 | When a new, lower level driver is being added to Linux, the following |
123 | files (all found in the drivers/scsi directory) will need some attention: |
124 | Makefile, Config.help and Config.in . It is probably best to look at what |
125 | an existing lower level driver does in this regard. |
126 | </para> |
127 | </chapter> |
128 | |
129 | <chapter id="intfunctions"> |
130 | <title>Interface Functions</title> |
131 | !EDocumentation/scsi/scsi_mid_low_api.txt |
132 | </chapter> |
133 | |
134 | <chapter id="locks"> |
135 | <title>Locks</title> |
136 | <para> |
137 | Each Scsi_Host instance has a spin_lock called Scsi_Host::default_lock |
138 | which is initialized in scsi_register() [found in hosts.c]. Within the |
139 | same function the Scsi_Host::host_lock pointer is initialized to point |
140 | at default_lock with the scsi_assign_lock() function. Thereafter |
141 | lock and unlock operations performed by the mid level use the |
142 | Scsi_Host::host_lock pointer. |
143 | </para> |
144 | <para> |
145 | Lower level drivers can override the use of Scsi_Host::default_lock by |
146 | using scsi_assign_lock(). The earliest opportunity to do this would |
147 | be in the detect() function after it has invoked scsi_register(). It |
148 | could be replaced by a coarser grain lock (e.g. per driver) or a |
149 | lock of equal granularity (i.e. per host). Using finer grain locks |
150 | (e.g. per scsi device) may be possible by juggling locks in |
151 | queuecommand(). |
152 | </para> |
153 | </chapter> |
154 | |
155 | <chapter id="changes"> |
156 | <title>Changes since lk 2.4 series</title> |
157 | <para> |
158 | io_request_lock has been replaced by several finer grained locks. The lock |
159 | relevant to lower level drivers is Scsi_Host::host_lock and there is one |
160 | per scsi host. |
161 | </para> |
162 | <para> |
163 | The older error handling mechanism has been removed. This means the |
164 | lower level interface functions abort() and reset() have been removed. |
165 | </para> |
166 | <para> |
167 | In the 2.4 series the scsi subsystem configuration descriptions were |
168 | aggregated with the configuration descriptions from all other Linux |
169 | subsystems in the Documentation/Configure.help file. In the 2.5 series, |
170 | the scsi subsystem now has its own (much smaller) drivers/scsi/Config.help |
171 | file. |
172 | </para> |
173 | </chapter> |
174 | |
175 | <chapter id="credits"> |
176 | <title>Credits</title> |
177 | <para> |
178 | The following people have contributed to this document: |
179 | <orderedlist> |
180 | <listitem><para> |
181 | Mike Anderson <email>andmike@us.ibm.com</email> |
182 | </para></listitem> |
183 | <listitem><para> |
184 | James Bottomley <email>James.Bottomley@steeleye.com</email> |
185 | </para></listitem> |
186 | <listitem><para> |
187 | Patrick Mansfield <email>patmans@us.ibm.com</email> |
188 | </para></listitem> |
189 | </orderedlist> |
190 | </para> |
191 | </chapter> |
192 | |
193 | </book> |