====================================================================
                      eComStation AHCI Driver
====================================================================


Introduction
============

OS2AHCI is an AHCI driver for eComStation. 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


Licensing and Source Code
=========================

The *binary* delivery of OS2AHCI.ADD as obtained from ecomstation.nl,
or as part of packaged eComStation releases, is licensed to run with
eComStation, only.

The source code can be retrieved from http://svn.ecomstation.nl;
in compliance to the GNU General Public License, the source code
can of course be modified/compiled to run on other products as long
as modifications will also be published as outlined in the GNU GPL2.

The toolchain required for compilation consists of:

 - IBM OS/2 DDK version 9.23 or later (see ddk\base\h\version.mak)
 - Microsoft C600 
 - ALP Assembler (part of DDK)
 - link.exe (part of DDK)


Watcom Build
------------

The source tree contains several files that were created during an
attempt to use the Watcom compiler (e.g. wmakefile); however, the
Watcom build is broken and produces a non-working driver.


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.
                       If <addr> is set to 0, the COM port is turned off and
                       all output is directed to an internal trace ring buffer
                       that can be dumped on an OS/2 command prompt with the
                       command "type os2ahci$"; see the OS2AHCI project page
                       at http://svn.ecomstation.nl/ahci/wiki/AhciTrace
                       for more info.
/d                     Debug output on COM port/trace buffer; multiple "/d" 
                       options will increase verbosity:
                         1 = requests
                         2 = detailed
                         3 = verbose, including MMIO operations
/v                     display adapter info during boot
/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 controller 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


Native Command Queuing
======================

Native Command Queuing (NCQ) is a feature which allows sending multiple I/O
requests to hard disks before waiting for any of the requests to complete,
much like Tagged Command Queuing for SCSI devices. This allows the disks
to reorder I/O requests to minimize head movements, resulting in improved
performance when executing random I/Os. In practice, this will be most
noticable when multiple programs request I/O services to different parts
of the disk -- a single program typically won't queue up I/O's but instead
will wait for each I/O to complete (with the exception of programs like
database servers).

While we believe NCQ will work with the majority of controllers and hard
disks, it's currently turned off by default until we have more feedback
from eComStation users. In order to turn on NCQ, just add the command line
option "/n" to OS2AHCI.ADD.


Interoperability With IDE Drivers
=================================

There are three kinds of IDE/ATA/SATA controllers:

 1. Legacy controllers (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 controllers 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 controllers
    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 and the PATA/IDE 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.

