source: trunk/src/os2ahci/README@ 174

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

Fix for hardware that reports incorrect status.
Now report both real and fake devices when SCSI emulation is enabled.

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