1 | ====================================================================
|
---|
2 | eComStation AHCI Driver
|
---|
3 | ====================================================================
|
---|
4 |
|
---|
5 |
|
---|
6 | Introduction
|
---|
7 | ============
|
---|
8 |
|
---|
9 | OS2AHCI is an AHCI driver for eComStation. It supports both ATA and
|
---|
10 | ATAPI devices in a single driver, thus there's no need for an
|
---|
11 | ATAPI/CDROM filter driver.
|
---|
12 |
|
---|
13 |
|
---|
14 | Copyrights
|
---|
15 | ==========
|
---|
16 |
|
---|
17 | Copyright (c) 2011 thi.guten Software Development
|
---|
18 | Copyright (c) 2011-2013 Mensys B.V.
|
---|
19 |
|
---|
20 | Authors: Christian Mueller, Markus Thielen
|
---|
21 |
|
---|
22 | Parts copied from/inspired by the Linux AHCI driver;
|
---|
23 | those parts are (c) Linux AHCI/ATA maintainers
|
---|
24 |
|
---|
25 | This program is free software; you can redistribute it and/or modify
|
---|
26 | it under the terms of the GNU General Public License as published by
|
---|
27 | the Free Software Foundation; either version 2 of the License, or
|
---|
28 | (at your option) any later version.
|
---|
29 |
|
---|
30 | This program is distributed in the hope that it will be useful,
|
---|
31 | but WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
32 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
---|
33 | GNU General Public License for more details.
|
---|
34 |
|
---|
35 | You should have received a copy of the GNU General Public License
|
---|
36 | along with this program; if not, write to the Free Software
|
---|
37 | Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
---|
38 | MA 02111-1307 USA
|
---|
39 |
|
---|
40 |
|
---|
41 | Licensing and Source Code
|
---|
42 | =========================
|
---|
43 |
|
---|
44 | The *binary* delivery of OS2AHCI.ADD as obtained from ecomstation.nl,
|
---|
45 | or as part of packaged eComStation releases, is licensed to run with
|
---|
46 | eComStation only.
|
---|
47 |
|
---|
48 | The source code can be retrieved from http://svn.ecomstation.nl;
|
---|
49 | in compliance to the GNU General Public License, the source code
|
---|
50 | can of course be modified/compiled to run on other products as long
|
---|
51 | as modifications will also be published as outlined in the GNU GPL2.
|
---|
52 |
|
---|
53 | Please note that builds other than the official binary delivered as
|
---|
54 | part of eComStation releases or downloaded from ecomstation.nl are
|
---|
55 | not officially supported by Mensys.
|
---|
56 |
|
---|
57 |
|
---|
58 | Building The Driver
|
---|
59 | -------------------
|
---|
60 |
|
---|
61 | The toolchain required for compilation consists of:
|
---|
62 |
|
---|
63 | - IBM OS/2 DDK version 9.23 or later (see ddk\base\h\version.mak)
|
---|
64 | and that has been updated for SMP systems. (Used for include files)
|
---|
65 | - Open Watcom C/C++ package
|
---|
66 | (available from: http://www.openwatcom.org/index.php/Downloads)
|
---|
67 | - WCC 16-bit C Compiler (part of the Open Watcom package)
|
---|
68 | - WASM Assembler (part of the Open Watcom package)
|
---|
69 | - WLINK Linker (part of the Open Watcom package)
|
---|
70 | - MAPSYM (part of the DDK)
|
---|
71 |
|
---|
72 | Define DDK and WATCOM in the environment.
|
---|
73 | Use "wmake" or "wmake -a" to build the driver. See _build.cmd.
|
---|
74 |
|
---|
75 | Installation
|
---|
76 | ============
|
---|
77 |
|
---|
78 | - Run the included update.cmd,
|
---|
79 | or copy the driver file, OS2AHCI.ADD, to \OS2\BOOT on your boot disk.
|
---|
80 |
|
---|
81 | - Add the following line to CONFIG.SYS:
|
---|
82 | BASEDEV=OS2AHCI.ADD
|
---|
83 |
|
---|
84 |
|
---|
85 | Driver Command Line Options
|
---|
86 | ===========================
|
---|
87 |
|
---|
88 | Global Options
|
---|
89 |
|
---|
90 | Option Description
|
---|
91 | ------------------------------------------------------------------------------
|
---|
92 | /b:<baud> Initialize the COM port to the specified baud rate. Allowable
|
---|
93 | baud values are: 300, 600, 1200, 2400, 4800, 9600, 19200,
|
---|
94 | 38400, 57600, and 115200. /b has no effect if /c is not also
|
---|
95 | specified. If /b is not specified, the COM port is not
|
---|
96 | initialized. For example, if you are using the kernel debugger,
|
---|
97 | the kernel debugger initializes the COM port so you should not
|
---|
98 | use this switch.
|
---|
99 |
|
---|
100 | /c:<n> Set debug COM port base address. Values for n can be:
|
---|
101 | 1 = COM1
|
---|
102 | 2 = COM2
|
---|
103 | a hex value (COM port base address) COM1=3f8, COM2=2f8
|
---|
104 | The default is 0. If set to 0 then no output goes to the COM port.
|
---|
105 |
|
---|
106 | /d[:n] Debug output to COM port/trace buffer. Values for n can be:
|
---|
107 | 1 = requests
|
---|
108 | 2 = detailed
|
---|
109 | 3 = verbose, including MMIO operations
|
---|
110 | If :n is not specified the debug level is incremented for
|
---|
111 | each /d specified.
|
---|
112 |
|
---|
113 | /w Allows the trace buffer to wrap when full.
|
---|
114 |
|
---|
115 | /v[:n] Display informational messages during boot. Values for n can be:
|
---|
116 | 1 = Display sign on banner
|
---|
117 | 2 = Display adapter information
|
---|
118 | If :n is not specified the verbosity level is incremented for
|
---|
119 | each /v specified.
|
---|
120 |
|
---|
121 | /g:<vendor>:<device> Add generic PCI ID to list of supported AHCI adapters
|
---|
122 | (e.g. /g:8086:2829)
|
---|
123 |
|
---|
124 | /t Perform thorough PCI ID scan; default = on, can be
|
---|
125 | turned off with /!t to perform only a PCI class scan
|
---|
126 |
|
---|
127 | /f Force the use of the HW write cache when using NCQ
|
---|
128 | commands; see "Native Command Queuing" below for
|
---|
129 | further explanation (default = off)
|
---|
130 |
|
---|
131 | /r Reset ports during initialization (default = on)
|
---|
132 | Can be turned off with /!r, however, when the
|
---|
133 | [Intel] AHCI controller was found to be
|
---|
134 | initialized by the BIOS in SATA mode, ports will
|
---|
135 | always be reset even when /!r was specified
|
---|
136 |
|
---|
137 | /a:n Set adapter to n for adapter-specific options
|
---|
138 | (default = -1, all adapters)
|
---|
139 |
|
---|
140 | /p:n Set port to n for port-specific options
|
---|
141 | (default = -1, all ports)
|
---|
142 |
|
---|
143 | Adapter-specific Options
|
---|
144 |
|
---|
145 | Option Description
|
---|
146 | ------------------------------------------------------------------------------
|
---|
147 | /i Ignore current adapter
|
---|
148 |
|
---|
149 | Port-specific Options
|
---|
150 |
|
---|
151 | Option Description
|
---|
152 | ------------------------------------------------------------------------------
|
---|
153 | /s Enable SCSI emulation for ATAPI units (default = off)
|
---|
154 | SCSI emulation is required for tools like cdrecord.
|
---|
155 |
|
---|
156 | /n Enable NCQ (Native Command Queuing) for hard disks
|
---|
157 | (default = off)
|
---|
158 |
|
---|
159 | /ls Set link speed (default = 0):
|
---|
160 | 0 = maximum,
|
---|
161 | 1 = limit to generation 1
|
---|
162 | 2 = limit to generation 2
|
---|
163 | 3 = limit to generation 3
|
---|
164 |
|
---|
165 | /lp Set link power management (default = 0):
|
---|
166 | 0 = full power management,
|
---|
167 | 1 = transitions to "partial slumber state" disabled,
|
---|
168 | 2 = transitions to "slumber state" disabled,
|
---|
169 | 3 = transitions to both partial and slumber states disabled
|
---|
170 |
|
---|
171 | /4 Force track size to be 56 sectors regardless of the
|
---|
172 | reported disk geometry to optimize partition boundaries
|
---|
173 | for hard disks with 4096 byte sectors.
|
---|
174 |
|
---|
175 | Port-specific options depend on the currently active adapter
|
---|
176 | and port selector (/a and /p). Those selectors are -1 per default
|
---|
177 | which means "all" adapters/ports. The scope can be reduced by limiting
|
---|
178 | it to an adapter (/a) or an adapter and a port (/a and /p). The scope
|
---|
179 | can be reset by setting the corresponding option back to -1.
|
---|
180 |
|
---|
181 | For example:
|
---|
182 |
|
---|
183 | BASEDEV=OS2AHCI.ADD /n /a:0 /p:5 /!n /a:1 /p:-1 /!n
|
---|
184 |
|
---|
185 | This has the following effect:
|
---|
186 |
|
---|
187 | - Enable NCQ for all hard disks
|
---|
188 | - Disable NCQ for hard disk on adapter #0, port #5
|
---|
189 | - Disable NCQ for all hard disks on adapter #1
|
---|
190 |
|
---|
191 |
|
---|
192 | Native Command Queuing
|
---|
193 | ======================
|
---|
194 |
|
---|
195 | Native Command Queuing (NCQ) is a feature which allows sending multiple I/O
|
---|
196 | requests to hard disks before waiting for any of the requests to complete,
|
---|
197 | much like Tagged Command Queuing for SCSI devices. This allows the disks
|
---|
198 | to reorder I/O requests to minimize head movements, resulting in improved
|
---|
199 | performance when executing random I/Os. In practice, this will be most
|
---|
200 | noticable when multiple programs request I/O services to different parts
|
---|
201 | of the disk -- a single program typically won't queue up I/O's but instead
|
---|
202 | will wait for each I/O to complete (with the exception of programs like
|
---|
203 | database servers).
|
---|
204 |
|
---|
205 | While we believe NCQ will work with the majority of controllers and hard
|
---|
206 | disks, it's currently turned off by default until we have more feedback
|
---|
207 | from eComStation users. In order to turn on NCQ, just add the command line
|
---|
208 | option "/n" to OS2AHCI.ADD.
|
---|
209 |
|
---|
210 | NCQ and HW Caches
|
---|
211 | -----------------
|
---|
212 |
|
---|
213 | In NCQ mode, OS2AHCI supports a request flag which allows upstream code
|
---|
214 | (e.g. file systems) to force writes to go directly to the disk instead
|
---|
215 | of being buffered in the HW disk cache. However, at least JFS doesn't
|
---|
216 | support this flag properly which effectively disables the HW disk cache
|
---|
217 | for write operations across the board, resulting in a substantial
|
---|
218 | performance loss. In order to prevent OS2AHCI from disabling the HW
|
---|
219 | cache when so requested by upstream code, please use the command line
|
---|
220 | option "/f".
|
---|
221 |
|
---|
222 | This may, of course, result in data loss in case of power failures but
|
---|
223 | apparently this was the situation with previous IDE drivers as well thus
|
---|
224 | shouldn't make much difference in the field. The JFS code also seems to
|
---|
225 | imply that this flag has never been widely supported by [IDE] drivers;
|
---|
226 | otherwise, the JFS developers should have stumbled over the performance
|
---|
227 | loss a long time ago and fixed the code.
|
---|
228 |
|
---|
229 | NOTES:
|
---|
230 |
|
---|
231 | - Without NCQ, OS2AHCI behaves like former IDE drivers, i.e. the HW
|
---|
232 | cache will always be enabled (on modern disks).
|
---|
233 |
|
---|
234 | - When suspending, rebooting or shutting down, OS2AHCI always flushes
|
---|
235 | the HW disk cache regardless of the "/f" or "/n" command line options.
|
---|
236 |
|
---|
237 |
|
---|
238 | Interoperability With IDE Drivers
|
---|
239 | =================================
|
---|
240 |
|
---|
241 | There are three kinds of IDE/ATA/SATA controllers:
|
---|
242 |
|
---|
243 | 1. Legacy controllers (IDE or SATA) without AHCI support
|
---|
244 | This kind of controller will only be recognized by IDE drivers
|
---|
245 | (IBM1S506.ADD or DANIS506.ADD).
|
---|
246 |
|
---|
247 | 2. AHCI-capable controllers which supports IDE/SATA legacy interfaces
|
---|
248 | This kind of controller will work with IDE or AHCI drivers and it's
|
---|
249 | up to the user to decide which driver to use.
|
---|
250 |
|
---|
251 | 3. AHCI-only controllers
|
---|
252 | This kind of controller will only be recognized by OS2AHCI.
|
---|
253 |
|
---|
254 | If there's a mix of controllers of types 1 and 3, both an IDE and an AHCI
|
---|
255 | driver will be required.
|
---|
256 |
|
---|
257 | If type 2 controllers are involved, it's up to the user to decide which
|
---|
258 | driver to use. Both DANIS506.ADD and OS2AHCI.ADD will verify whether another
|
---|
259 | driver has already allocated the corresponding adapter, thus the only
|
---|
260 | decision to take for mixed configurations is whether type-2 controllers
|
---|
261 | should be handled by DANIS506.ADD or OS2AHCI.ADD and this can be done by
|
---|
262 | having the desired driver's BASEDEV statement coming first in CONFIG.SYS.
|
---|
263 |
|
---|
264 | NOTE: Older versions of DANIS506.ADD did not verify whether the resources
|
---|
265 | of a particular adapter were already allocated by another driver.
|
---|
266 | DANIS506.ADD 1.8.8 or later is required for this to work.
|
---|
267 |
|
---|
268 | When using earlier versions of DANI1S506.ADD, the options "/A:x /I"
|
---|
269 | will be required to tell DANI1S506.ADD to ignore adapters to be
|
---|
270 | driven by OS2AHCI.ADD. The same applies to IBM1S506.ADD
|
---|
271 |
|
---|
272 | Mixed Controller Example
|
---|
273 | ------------------------
|
---|
274 |
|
---|
275 | Assume a DELL D630 or a Thinkpad T60. The hard disk is attached to the
|
---|
276 | SATA/AHCI controller of the ICH-7 hub while the CDROM is attached to the
|
---|
277 | legacy PATA IDE controller. This allows two different configurations:
|
---|
278 |
|
---|
279 | 1. Drive HDD and CDROM via DANIS506.ADD
|
---|
280 | 2. Drive HDD via OS2AHCI.ADD and CDROM via DANI1S506.ADD
|
---|
281 |
|
---|
282 | OS2AHCI.ADD can't drive the CDROM because it's attached to a legacy PATA
|
---|
283 | IDE controller which doesn't support AHCI.
|
---|
284 |
|
---|
285 | - If OS2AHCI.ADD comes first in CONFIG.SYS, it will take over the SATA/AHCI
|
---|
286 | controller and drive the HDD. DANIS506.ADD will take care of the PATA/IDE
|
---|
287 | controller for the CDROM.
|
---|
288 | - If DANIS506.ADD comes first in CONFIG.SYS, it will take over both the
|
---|
289 | SATA/AHCI and the PATA/IDE controller and OS2AHCI.ADD will silently exit.
|
---|
290 |
|
---|
291 | Advantages of AHCI
|
---|
292 | ------------------
|
---|
293 |
|
---|
294 | The interfaces provided by the various [Intel] controllers could be
|
---|
295 | summarized like this (the term ATA as driver interface being a bit of our
|
---|
296 | own invention):
|
---|
297 |
|
---|
298 | - Intel PIIX: IDE (I/O registers) and ATA (taskfile)
|
---|
299 | - Intel ICH6: IDE (I/O registers), ATA (taskfile) and SATA
|
---|
300 | (FIS, vendor-specific)
|
---|
301 | - Intel ICH7: IDE (I/O registers), ATA (taskfile), SATA
|
---|
302 | (FIS, vendor-specific) and AHCI (FIS)
|
---|
303 | - Intel PCH: AHCI (FIS)
|
---|
304 |
|
---|
305 | Taskfiles are regions in memory with ATA commands which the IDE/ATA
|
---|
306 | controller can read and process autonomously. FIS (Frame Information
|
---|
307 | Structures) are pretty much the same but they are specific to the SATA
|
---|
308 | communication protocol on the serial link. The most important FIS type
|
---|
309 | for AHCI drivers is the H2D (host to device) FIS which basically contains
|
---|
310 | the ATA command to be executed.
|
---|
311 |
|
---|
312 | The big advantage of AHCI controllers, apart from being vendor-neutral,
|
---|
313 | is that they take care of a lot of things which previous-generation
|
---|
314 | drivers like DANI1S506 would have to do step by step. For example, in
|
---|
315 | order to send an ATAPI command, DANIS506 would have to do the following:
|
---|
316 |
|
---|
317 | * Send ATA "PACKET" command to device (via IDE registers, ATA taskfiles
|
---|
318 | or SATA FIS)
|
---|
319 | * Wait until device signals via interrupt it's ready for the ATAPI command
|
---|
320 | * Send ATAPI command to device via PIO
|
---|
321 | * Wait until device signals via interrupt it's ready to transfer data
|
---|
322 | * Send/Receive any data that might come along with the ATAPI command via
|
---|
323 | PIO, or wait for DMA transfer to complete
|
---|
324 | * Wait until device signals via interrupt that command and data transfer
|
---|
325 | have completed
|
---|
326 |
|
---|
327 | For OS2AHCI, the same operation looks like this:
|
---|
328 |
|
---|
329 | * Fill in AHCI command header, FIS with ATA "PACKET" command and the ATAPI
|
---|
330 | command
|
---|
331 | * Tell port engine to process the command
|
---|
332 | * Wait until controller signals via interrupt that command and data
|
---|
333 | transfer have completed
|
---|
334 |
|
---|
335 | The AHCI controller automatically takes care of all underlying bits and
|
---|
336 | pieces. OS2AHCI doesn't even have to know whether a particular message is
|
---|
337 | sent via PIO or DMA because this is handled by the AHCI controller, too.
|
---|
338 | And the whole concept of PIO and DMA is only relevant between AHCI controller
|
---|
339 | and the device -- all transfers between OS2AHCI and the AHCI controller are
|
---|
340 | always done via DMA.
|
---|
341 |
|
---|
342 |
|
---|
343 | SMART Support
|
---|
344 | =============
|
---|
345 |
|
---|
346 | Starting with version 1.22, OS2AHCI supports the IOCTL interface required by
|
---|
347 | existing SMART monitoring tools. Since those tools are hard-coded to open
|
---|
348 | the character device named "IBMS506$", OS2AHCI will now register a device
|
---|
349 | with this name, too.
|
---|
350 |
|
---|
351 | NOTES:
|
---|
352 |
|
---|
353 | - If multiple drivers exporting this character device name are loaded at
|
---|
354 | the same time, the driver loaded last will receive all [SMART] requests.
|
---|
355 | This means that if both DANIS506 and OS2AHCI are loaded and SMART support
|
---|
356 | for OS2AHCI-controlled hard disks is desired, OS2AHCI will have to be
|
---|
357 | loaded after DANIS506. It also means that DANIS506 may have to be told
|
---|
358 | to ignore type 2 controllers (i.e. controllers supporting both SATA and
|
---|
359 | AHCI) using the command line options "/A:x /I".
|
---|
360 |
|
---|
361 | - The IOCTL interface for SMART is based on the idea of IDE controllers
|
---|
362 | with a master and a slave drive. OS2AHCI maps all devices (ATA or ATAPI)
|
---|
363 | sequentially to this pattern. If, for example, you have 4 hard disks and
|
---|
364 | one CDROM attached to a single controller on ports 1, 2, 5, 7, and 11,
|
---|
365 | SMART tools will see 3 controllers as follows:
|
---|
366 |
|
---|
367 | - controller 0, master: HD on port 1
|
---|
368 | - controller 0, slave: HD on port 2
|
---|
369 | - controller 1, master: HD on port 5
|
---|
370 | - controller 1, slave: HD on port 7
|
---|
371 | - controller 2, master: CDROM on port 11
|
---|
372 |
|
---|
373 | - The DSKSP_GEN_GET_COUNTERS interface is currently unsupported; calls to
|
---|
374 | the corresponding IOCTL will return 0 for all counters. SMART counters
|
---|
375 | are not affected by this limitation, i.e. SMART tools will be able to
|
---|
376 | report counters from the physical disk; this limitation only affects
|
---|
377 | the software counters maintained by ADD drivers which do support the
|
---|
378 | DSKSP_GEN_GET_COUNTERS IOCTL request.
|
---|
379 |
|
---|
380 |
|
---|
381 | Change Log
|
---|
382 | ==========
|
---|
383 |
|
---|
384 | v.1.28 01-Jun-2013 - David Azarewicz
|
---|
385 | Reworked trap dump kernel exit
|
---|
386 | Removed unused IDC entry point.
|
---|
387 | Reworked suspend/resume routines.
|
---|
388 | Implemented a temporary hack to make resume work reasonably well.
|
---|
389 | Suspend/resume is only supported on eCS systems with ACPI.
|
---|
390 | Suspend/resume is known to not work reliably and cannot be further
|
---|
391 | addressed in this driver.
|
---|
392 |
|
---|
393 | v.1.27 23-Apr-2013 - David Azarewicz
|
---|
394 | Added LVM aware disk geometry reporting.
|
---|
395 | Begin to add disk information report - not finished yet.
|
---|
396 | Removed undocumented /q switch and made the driver quiet by default.
|
---|
397 | Debug output improvements.
|
---|
398 | Added /b switch for setting debug baud rate.
|
---|
399 | Fixed up time delay functions
|
---|
400 |
|
---|
401 | v.1.26 26-Mar-2013 - David Azarewicz
|
---|
402 | Fix spin-up / power-up issue on some hardware
|
---|
403 | Reorganized and improved debug output.
|
---|
404 |
|
---|
405 | v.1.26 21-Feb-2013 - rousseau
|
---|
406 | Virtual box fix
|
---|
407 | Some SMP fixes
|
---|
408 | Changed default for port reset to always
|
---|
409 |
|
---|
410 | v.1.25 02-Oct-2012 - markus.thi
|
---|
411 | Added support for trap dumps
|
---|
412 |
|
---|
413 | v.1.24 21-May-2012 - markus.thi
|
---|
414 | Fixed JFS long format hang (ticket 16)
|
---|
415 |
|
---|
416 | V.1.23 16-May-2012 - markus.thi
|
---|
417 | added IDC entry point to allow switching back to BIOS mode
|
---|
418 |
|
---|
419 | v.1.22 17-Oct-2011 - markus.thi
|
---|
420 | Added "IBMS506" header to accomodate broken SMART tools.
|
---|