source: trunk/src/os2ahci/README@ 177

Last change on this file since 177 was 177, checked in by David Azarewicz, 9 years ago

Repository cleanup

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