source: trunk/src/os2ahci/README@ 165

Last change on this file since 165 was 165, checked in by David Azarewicz, 12 years ago

code cleanup - debug messages
fixed defect in smart ioctl

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