source: trunk/src/os2ahci/README@ 178

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

Major reorganization

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