Index: trunk/src/os2ahci/README
===================================================================
--- trunk/src/os2ahci/README	(revision 90)
+++ trunk/src/os2ahci/README	(revision 90)
@@ -0,0 +1,224 @@
+====================================================================
+                      eComStation AHCI Driver
+====================================================================
+
+
+Introduction
+============
+
+OS2AHCI is an AHCI driver for eComStation and OS/2 3.x or later. It
+supports both ATA and ATAPI devices in a single driver, thus there's
+no need for an ATAPI/CDROM filter driver.
+
+
+Copyrights
+==========
+
+Copyright (c) 2011 thi.guten Software Development
+Copyright (c) 2011 Mensys B.V.
+
+Authors: Christian Mueller, Markus Thielen
+
+Parts copied from/inspired by the Linux AHCI driver;
+those parts are (c) Linux AHCI/ATA maintainers
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+Installation
+============
+
+- Copy the driver file, OS2AHCI.ADD, to C:\OS2\BOOT
+
+- Add the following line to CONFIG.SYS:
+  BASEDEV=OS2AHCI.ADD
+
+
+Driver Command Line Options
+===========================
+
+Global Options
+
+Option                 Description
+------------------------------------------------------------------------------
+/c:<addr>              Set debug COM port base address in hex (default = 3f8);
+                       if used, this option should come before any /d options.
+/d                     Debug output on COM port; multiple "/d" options will
+                       increase verbosity:
+                         1 = requests
+                         2 = detailed
+                         3 = verbose, including MMIO operations
+/g:<vendor>:<device>   Add generic PCI ID to list of supported AHCI adapters
+                       (e.g. /g:8086:2829)
+/t                     Perform thorough PCI ID scan; default = on, can be
+                       turned off with /!t to perform only a PCI class scan
+/r                     Reset ports during initialization (default = off
+                       unless the [Intel] AHCI was found to be initialized
+                       by the BIOS to SATA mode)
+/a                     Set adapter for adapter-specific options
+                       (default = -1, all adapters)
+/p                     Set port for port-specific options
+                       (default = -1, all ports)
+
+Adapter-specific Options
+
+Option                 Description
+------------------------------------------------------------------------------
+/i                     Ignore current adapter
+
+Port-specific Options
+
+Option                 Description
+------------------------------------------------------------------------------
+/s                     Enable SCSI emulation for ATAPI units (default = off)
+                       SCSI emulation is required for tools like cdrecord.
+/n                     Enable NCQ (Native Command Queuing) for hard disks
+                       (default = off)
+/ls                    Set link speed (default = 0):
+                         0 = maximum,
+                         1 = limit to generation 1
+                         2 = limit to generation 2
+                         3 = limit to generation 3
+/lp                    Set link power management (default = 0):
+                         0 = full power management,
+                         1 = transitions to "partial slumber state" disabled,
+                         2 = transitions to "slumber state" disabled,
+                         3 = transitions to both partial and slumber states
+                             disabled
+/4                     Force track size to be 56 sectors regardless of the
+                       reported disk geometry to optimize partition boundaries
+                       for hard disks with 4096 byte sectors.
+
+Port-specific options depend on the currently active adapter
+and port selector (/a and /p). Those selectors are -1 per default
+which means "all" adapters/ports. The scope can be reduced by limiting
+it to an adapter (/a) or an adapter and a port (/a and /p). The scope
+can be reset by setting the corresponding option back to -1.
+
+For example:
+
+  BASEDEV=OS2AHCI.ADD /n /a:0 /p:5 /!n /a:1 /p:-1 /!n
+
+This has the following effect:
+  
+  - Enable NCQ for all hard disks
+  - Disable NCQ for hard disk on adapter #0, port #5
+  - Disable NCQ for all hard disks on adapter #1
+
+
+Interoperability With IDE Drivers
+=================================
+
+There are three kinds of IDE/ATA/SATA controllers:
+
+ 1. Legacy controller (IDE or SATA) without AHCI support
+    This kind of controller will only be recognized by IDE drivers
+    (IBM1S506.ADD or DANIS506.ADD).
+
+ 2. AHCI-capable controller which supports IDE/SATA legacy interfaces
+    This kind of controller will work with IDE or AHCI drivers and it's
+    up to the user to decide which driver to use.
+
+ 3. AHCI-only controller
+    This kind of controller will only be recognized by OS2AHCI.
+
+If there's a mix of controllers of types 1 and 3, both an IDE and an AHCI
+driver will be required.
+
+If type 2 controllers are involved, it's up to the user to decide which
+driver to use. Both DANIS506.ADD and OS2AHCI.ADD will verify whether another
+driver has already allocated the corresponding adapter, thus the only
+decision to take for mixed configurations is whether type-2 controllers
+should be handled by DANIS506.ADD or OS2AHCI.ADD and this can be done by
+having the desired driver's BASEDEV statement coming first in CONFIG.SYS.
+
+NOTE: Older versions of DANIS506.ADD did not verify whether the resources
+      of a particular adapter were already allocated by another driver.
+      DANIS506.ADD 1.8.8 or later is required for this to work.
+
+      When using earlier versions of DANI1S506.ADD, the options "/A:x /I"
+      will be required to tell DANI1S506.ADD to ignore adapters to be
+      driven by OS2AHCI.ADD. The same applies to IBM1S506.ADD
+
+Mixed Controller Example
+------------------------
+
+Assume a DELL D630 or a Thinkpad T60. The hard disk is attached to the
+SATA/AHCI controller of the ICH-7 hub while the CDROM is attached to the
+legacy PATA IDE controller. This allows two different configurations:
+
+ 1. Drive HDD and CDROM via DANIS506.ADD
+ 2. Drive HDD via OS2AHCI.ADD and CDROM via DANI1S506.ADD
+
+OS2AHCI.ADD can't drive the CDROM because it's attached to a legacy PATA
+IDE controller which doesn't support AHCI.
+
+ - If OS2AHCI.ADD comes first in CONFIG.SYS, it will take over the SATA/AHCI
+   controller and drive the HDD. DANIS506.ADD will take care of the PATA/IDE
+   controller for the CDROM.
+ - If DANIS506.ADD comes first in CONFIG.SYS, it will take over both the
+   SATA/AHCI controller and OS2AHCI.ADD will silently exit.
+
+Advantages of AHCI
+------------------
+
+The interfaces provided by the various [Intel] controllers could be
+summarized like this (the term ATA as driver interface being a bit of our
+own invention):
+
+ - Intel PIIX: IDE (I/O registers) and ATA (taskfile)
+ - Intel ICH6: IDE (I/O registers), ATA (taskfile) and SATA
+   (FIS, vendor-specific)
+ - Intel ICH7: IDE (I/O registers), ATA (taskfile), SATA
+   (FIS, vendor-specific) and AHCI (FIS)
+ - Intel PCH: AHCI (FIS)
+
+Taskfiles are regions in memory with ATA commands which the IDE/ATA
+controller can read and process autonomously. FIS (Frame Information
+Structures) are pretty much the same but they are specific to the SATA
+communication protocol on the serial link. The most important FIS type
+for AHCI drivers is the H2D (host to device) FIS which basically contains
+the ATA command to be executed.
+
+The big advantage of AHCI controllers, apart from being vendor-neutral,
+is that they take care of a lot of things which previous-generation
+drivers like DANI1S506 would have to do step by step. For example, in
+order to send an ATAPI command, DANIS506 would have to do the following:
+
+  * Send ATA "PACKET" command to device (via IDE registers, ATA taskfiles
+    or SATA FIS)
+  * Wait until device signals via interrupt it's ready for the ATAPI command
+  * Send ATAPI command to device via PIO
+  * Wait until device signals via interrupt it's ready to transfer data
+  * Send/Receive any data that might come along with the ATAPI command via
+    PIO, or wait for DMA transfer to complete
+  * Wait until device signals via interrupt that command and data transfer
+    have completed
+
+For OS2AHCI, the same operation looks like this:
+
+  * Fill in AHCI command header, FIS with ATA "PACKET" command and the ATAPI
+    command
+  * Tell port engine to process the command
+  * Wait until controller signals via interrupt that command and data
+    transfer have completed
+
+The AHCI controller automatically takes care of all underlying bits and
+pieces. OS2AHCI doesn't even have to know whether a particular message is
+sent via PIO or DMA because this is handled by the AHCI controller, too.
+And the whole concept of PIO and DMA is only relevant between AHCI controller
+and the device -- all transfers between OS2AHCI and the AHCI controller are
+always done via DMA.
+
