source: trunk/src/os2ahci/ReadMe.txt

Last change on this file was 209, checked in by David Azarewicz, 8 months ago

Debugging support changes.

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