| 1 | ====================================================================
|
|---|
| 2 | eComStation AHCI Driver
|
|---|
| 3 | ====================================================================
|
|---|
| 4 |
|
|---|
| 5 |
|
|---|
| 6 | Introduction
|
|---|
| 7 | ============
|
|---|
| 8 |
|
|---|
| 9 | OS2AHCI is an AHCI driver for eComStation. It supports both ATA and
|
|---|
| 10 | ATAPI devices in a single driver, thus there's no need for an
|
|---|
| 11 | ATAPI/CDROM filter driver.
|
|---|
| 12 |
|
|---|
| 13 |
|
|---|
| 14 | Copyrights
|
|---|
| 15 | ==========
|
|---|
| 16 |
|
|---|
| 17 | Copyright (c) 2011 thi.guten Software Development
|
|---|
| 18 | Copyright (c) 2011-2013 Mensys B.V.
|
|---|
| 19 |
|
|---|
| 20 | Authors: Christian Mueller, Markus Thielen
|
|---|
| 21 |
|
|---|
| 22 | Parts copied from/inspired by the Linux AHCI driver;
|
|---|
| 23 | those 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 |
|
|---|
| 40 |
|
|---|
| 41 | Licensing and Source Code
|
|---|
| 42 | =========================
|
|---|
| 43 |
|
|---|
| 44 | The *binary* delivery of OS2AHCI.ADD as obtained from ecomstation.nl,
|
|---|
| 45 | or as part of packaged eComStation releases, is licensed to run with
|
|---|
| 46 | eComStation, only.
|
|---|
| 47 |
|
|---|
| 48 | The source code can be retrieved from http://svn.ecomstation.nl;
|
|---|
| 49 | in compliance to the GNU General Public License, the source code
|
|---|
| 50 | can of course be modified/compiled to run on other products as long
|
|---|
| 51 | as modifications will also be published as outlined in the GNU GPL2.
|
|---|
| 52 |
|
|---|
| 53 | Please note that builds other than the official binary delivered as
|
|---|
| 54 | part of eComStation releases or downloaded from ecomstation.nl are
|
|---|
| 55 | not officially supported by Mensys.
|
|---|
| 56 |
|
|---|
| 57 |
|
|---|
| 58 | Building The Driver
|
|---|
| 59 | -------------------
|
|---|
| 60 |
|
|---|
| 61 | The toolchain required for compilation consists of:
|
|---|
| 62 |
|
|---|
| 63 | - IBM OS/2 DDK version 9.23 or later (see ddk\base\h\version.mak)
|
|---|
| 64 | (Used for include files and qgrep)
|
|---|
| 65 | - Open Watcom C/C++ package
|
|---|
| 66 | (available from: http://www.openwatcom.org/index.php/Downloads)
|
|---|
| 67 | - WCC 16-bit C Compiler (part of the Open Watcom package)
|
|---|
| 68 | - WASM Assembler (part of the Open Watcom package)
|
|---|
| 69 | - WLINK Linker (part of the Open Watcom package)
|
|---|
| 70 | - MAPSYM (part of the DDK)
|
|---|
| 71 |
|
|---|
| 72 | Simply use "wmake" or "wmake -a" to build the driver.
|
|---|
| 73 |
|
|---|
| 74 | The driver can also be built using the DDK tools, but this build
|
|---|
| 75 | is depreciated and is not kept up-to-date.
|
|---|
| 76 |
|
|---|
| 77 | The toolchain required for compilation consists of:
|
|---|
| 78 |
|
|---|
| 79 | - IBM OS/2 DDK version 9.23 or later (see ddk\base\h\version.mak)
|
|---|
| 80 | - Microsoft C600
|
|---|
| 81 | - ALP Assembler (part of DDK)
|
|---|
| 82 | - link.exe (part of DDK)
|
|---|
| 83 | - MAPSYM (part of the DDK)
|
|---|
| 84 |
|
|---|
| 85 | Use "nmake -f Makefile.old" or "nmake -f Makefile.old -a" to build
|
|---|
| 86 | the driver.
|
|---|
| 87 |
|
|---|
| 88 | When switching between building with the DDK and Open Watcom, it is
|
|---|
| 89 | recommended to do a clean first (wmake clean or nmake -f Makefile.old clean).
|
|---|
| 90 |
|
|---|
| 91 |
|
|---|
| 92 | Installation
|
|---|
| 93 | ============
|
|---|
| 94 |
|
|---|
| 95 | - Copy the driver file, OS2AHCI.ADD, to C:\OS2\BOOT
|
|---|
| 96 |
|
|---|
| 97 | - Add the following line to CONFIG.SYS:
|
|---|
| 98 | BASEDEV=OS2AHCI.ADD
|
|---|
| 99 |
|
|---|
| 100 |
|
|---|
| 101 | Driver Command Line Options
|
|---|
| 102 | ===========================
|
|---|
| 103 |
|
|---|
| 104 | Global Options
|
|---|
| 105 |
|
|---|
| 106 | Option Description
|
|---|
| 107 | ------------------------------------------------------------------------------
|
|---|
| 108 | /c:<addr> Set debug COM port base address in hex (default = 3f8);
|
|---|
| 109 | if used, this option should come before any /d options.
|
|---|
| 110 | If <addr> is set to 0, the COM port is turned off and
|
|---|
| 111 | all output is directed to an internal trace ring buffer
|
|---|
| 112 | that can be dumped on an OS/2 command prompt with the
|
|---|
| 113 | command "type os2ahci$"; see the OS2AHCI project page
|
|---|
| 114 | at http://svn.ecomstation.nl/ahci/wiki/AhciTrace
|
|---|
| 115 | for more info.
|
|---|
| 116 | /d Debug output on COM port/trace buffer; multiple "/d"
|
|---|
| 117 | options will increase verbosity:
|
|---|
| 118 | 1 = requests
|
|---|
| 119 | 2 = detailed
|
|---|
| 120 | 3 = verbose, including MMIO operations
|
|---|
| 121 | /v display adapter info during boot
|
|---|
| 122 | /g:<vendor>:<device> Add generic PCI ID to list of supported AHCI adapters
|
|---|
| 123 | (e.g. /g:8086:2829)
|
|---|
| 124 | /t Perform thorough PCI ID scan; default = on, can be
|
|---|
| 125 | turned off with /!t to perform only a PCI class scan
|
|---|
| 126 | /f Force the use of the HW write cache when using NCQ
|
|---|
| 127 | commands; see "Native Command Queuing" below for
|
|---|
| 128 | further explanation (default = off)
|
|---|
| 129 | /r Reset ports during initialization (default = on)
|
|---|
| 130 | Can be turned off with /!r, however, when the
|
|---|
| 131 | [Intel] AHCI controller was found to be
|
|---|
| 132 | initialized by the BIOS in SATA mode, ports will
|
|---|
| 133 | always be reset even when /!r was specified
|
|---|
| 134 | /a Set adapter for adapter-specific options
|
|---|
| 135 | (default = -1, all adapters)
|
|---|
| 136 | /p Set port for port-specific options
|
|---|
| 137 | (default = -1, all ports)
|
|---|
| 138 |
|
|---|
| 139 | Adapter-specific Options
|
|---|
| 140 |
|
|---|
| 141 | Option Description
|
|---|
| 142 | ------------------------------------------------------------------------------
|
|---|
| 143 | /i Ignore current adapter
|
|---|
| 144 |
|
|---|
| 145 | Port-specific Options
|
|---|
| 146 |
|
|---|
| 147 | Option Description
|
|---|
| 148 | ------------------------------------------------------------------------------
|
|---|
| 149 | /s Enable SCSI emulation for ATAPI units (default = off)
|
|---|
| 150 | SCSI emulation is required for tools like cdrecord.
|
|---|
| 151 | /n Enable NCQ (Native Command Queuing) for hard disks
|
|---|
| 152 | (default = off)
|
|---|
| 153 | /ls Set link speed (default = 0):
|
|---|
| 154 | 0 = maximum,
|
|---|
| 155 | 1 = limit to generation 1
|
|---|
| 156 | 2 = limit to generation 2
|
|---|
| 157 | 3 = limit to generation 3
|
|---|
| 158 | /lp Set link power management (default = 0):
|
|---|
| 159 | 0 = full power management,
|
|---|
| 160 | 1 = transitions to "partial slumber state" disabled,
|
|---|
| 161 | 2 = transitions to "slumber state" disabled,
|
|---|
| 162 | 3 = transitions to both partial and slumber states
|
|---|
| 163 | disabled
|
|---|
| 164 | /4 Force track size to be 56 sectors regardless of the
|
|---|
| 165 | reported disk geometry to optimize partition boundaries
|
|---|
| 166 | for hard disks with 4096 byte sectors.
|
|---|
| 167 |
|
|---|
| 168 | Port-specific options depend on the currently active adapter
|
|---|
| 169 | and port selector (/a and /p). Those selectors are -1 per default
|
|---|
| 170 | which means "all" adapters/ports. The scope can be reduced by limiting
|
|---|
| 171 | it to an adapter (/a) or an adapter and a port (/a and /p). The scope
|
|---|
| 172 | can be reset by setting the corresponding option back to -1.
|
|---|
| 173 |
|
|---|
| 174 | For example:
|
|---|
| 175 |
|
|---|
| 176 | BASEDEV=OS2AHCI.ADD /n /a:0 /p:5 /!n /a:1 /p:-1 /!n
|
|---|
| 177 |
|
|---|
| 178 | This has the following effect:
|
|---|
| 179 |
|
|---|
| 180 | - Enable NCQ for all hard disks
|
|---|
| 181 | - Disable NCQ for hard disk on adapter #0, port #5
|
|---|
| 182 | - Disable NCQ for all hard disks on adapter #1
|
|---|
| 183 |
|
|---|
| 184 |
|
|---|
| 185 | Native Command Queuing
|
|---|
| 186 | ======================
|
|---|
| 187 |
|
|---|
| 188 | Native Command Queuing (NCQ) is a feature which allows sending multiple I/O
|
|---|
| 189 | requests to hard disks before waiting for any of the requests to complete,
|
|---|
| 190 | much like Tagged Command Queuing for SCSI devices. This allows the disks
|
|---|
| 191 | to reorder I/O requests to minimize head movements, resulting in improved
|
|---|
| 192 | performance when executing random I/Os. In practice, this will be most
|
|---|
| 193 | noticable when multiple programs request I/O services to different parts
|
|---|
| 194 | of the disk -- a single program typically won't queue up I/O's but instead
|
|---|
| 195 | will wait for each I/O to complete (with the exception of programs like
|
|---|
| 196 | database servers).
|
|---|
| 197 |
|
|---|
| 198 | While we believe NCQ will work with the majority of controllers and hard
|
|---|
| 199 | disks, it's currently turned off by default until we have more feedback
|
|---|
| 200 | from eComStation users. In order to turn on NCQ, just add the command line
|
|---|
| 201 | option "/n" to OS2AHCI.ADD.
|
|---|
| 202 |
|
|---|
| 203 | NCQ and HW Caches
|
|---|
| 204 | -----------------
|
|---|
| 205 |
|
|---|
| 206 | In NCQ mode, OS2AHCI supports a request flag which allows upstream code
|
|---|
| 207 | (e.g. file systems) to force writes to go directly to the disk instead
|
|---|
| 208 | of being buffered in the HW disk cache. However, at least JFS doesn't
|
|---|
| 209 | support this flag properly which effectively disables the HW disk cache
|
|---|
| 210 | for write operations across the board, resulting in a substantial
|
|---|
| 211 | performance loss. In order to prevent OS2AHCI from disabling the HW
|
|---|
| 212 | cache when so requested by upstream code, please use the command line
|
|---|
| 213 | option "/f".
|
|---|
| 214 |
|
|---|
| 215 | This may, of course, result in data loss in case of power failures but
|
|---|
| 216 | apparently this was the situation with previous IDE drivers as well thus
|
|---|
| 217 | shouldn't make much difference in the field. The JFS code also seems to
|
|---|
| 218 | imply that this flag has never been widely supported by [IDE] drivers;
|
|---|
| 219 | otherwise, the JFS developers should have stumbled over the performance
|
|---|
| 220 | loss a long time ago and fixed the code.
|
|---|
| 221 |
|
|---|
| 222 | NOTES:
|
|---|
| 223 |
|
|---|
| 224 | - Without NCQ, OS2AHCI behaves like former IDE drivers, i.e. the HW
|
|---|
| 225 | cache will always be enabled (on modern disks).
|
|---|
| 226 |
|
|---|
| 227 | - When suspending, rebooting or shutting down, OS2AHCI always flushes
|
|---|
| 228 | the HW disk cache regardless of the "/f" or "/n" command line options.
|
|---|
| 229 |
|
|---|
| 230 |
|
|---|
| 231 | Interoperability With IDE Drivers
|
|---|
| 232 | =================================
|
|---|
| 233 |
|
|---|
| 234 | There are three kinds of IDE/ATA/SATA controllers:
|
|---|
| 235 |
|
|---|
| 236 | 1. Legacy controllers (IDE or SATA) without AHCI support
|
|---|
| 237 | This kind of controller will only be recognized by IDE drivers
|
|---|
| 238 | (IBM1S506.ADD or DANIS506.ADD).
|
|---|
| 239 |
|
|---|
| 240 | 2. AHCI-capable controllers which supports IDE/SATA legacy interfaces
|
|---|
| 241 | This kind of controller will work with IDE or AHCI drivers and it's
|
|---|
| 242 | up to the user to decide which driver to use.
|
|---|
| 243 |
|
|---|
| 244 | 3. AHCI-only controllers
|
|---|
| 245 | This kind of controller will only be recognized by OS2AHCI.
|
|---|
| 246 |
|
|---|
| 247 | If there's a mix of controllers of types 1 and 3, both an IDE and an AHCI
|
|---|
| 248 | driver will be required.
|
|---|
| 249 |
|
|---|
| 250 | If type 2 controllers are involved, it's up to the user to decide which
|
|---|
| 251 | driver to use. Both DANIS506.ADD and OS2AHCI.ADD will verify whether another
|
|---|
| 252 | driver has already allocated the corresponding adapter, thus the only
|
|---|
| 253 | decision to take for mixed configurations is whether type-2 controllers
|
|---|
| 254 | should be handled by DANIS506.ADD or OS2AHCI.ADD and this can be done by
|
|---|
| 255 | having the desired driver's BASEDEV statement coming first in CONFIG.SYS.
|
|---|
| 256 |
|
|---|
| 257 | NOTE: Older versions of DANIS506.ADD did not verify whether the resources
|
|---|
| 258 | of a particular adapter were already allocated by another driver.
|
|---|
| 259 | DANIS506.ADD 1.8.8 or later is required for this to work.
|
|---|
| 260 |
|
|---|
| 261 | When using earlier versions of DANI1S506.ADD, the options "/A:x /I"
|
|---|
| 262 | will be required to tell DANI1S506.ADD to ignore adapters to be
|
|---|
| 263 | driven by OS2AHCI.ADD. The same applies to IBM1S506.ADD
|
|---|
| 264 |
|
|---|
| 265 | Mixed Controller Example
|
|---|
| 266 | ------------------------
|
|---|
| 267 |
|
|---|
| 268 | Assume a DELL D630 or a Thinkpad T60. The hard disk is attached to the
|
|---|
| 269 | SATA/AHCI controller of the ICH-7 hub while the CDROM is attached to the
|
|---|
| 270 | legacy PATA IDE controller. This allows two different configurations:
|
|---|
| 271 |
|
|---|
| 272 | 1. Drive HDD and CDROM via DANIS506.ADD
|
|---|
| 273 | 2. Drive HDD via OS2AHCI.ADD and CDROM via DANI1S506.ADD
|
|---|
| 274 |
|
|---|
| 275 | OS2AHCI.ADD can't drive the CDROM because it's attached to a legacy PATA
|
|---|
| 276 | IDE controller which doesn't support AHCI.
|
|---|
| 277 |
|
|---|
| 278 | - If OS2AHCI.ADD comes first in CONFIG.SYS, it will take over the SATA/AHCI
|
|---|
| 279 | controller and drive the HDD. DANIS506.ADD will take care of the PATA/IDE
|
|---|
| 280 | controller for the CDROM.
|
|---|
| 281 | - If DANIS506.ADD comes first in CONFIG.SYS, it will take over both the
|
|---|
| 282 | SATA/AHCI and the PATA/IDE controller and OS2AHCI.ADD will silently exit.
|
|---|
| 283 |
|
|---|
| 284 | Advantages of AHCI
|
|---|
| 285 | ------------------
|
|---|
| 286 |
|
|---|
| 287 | The interfaces provided by the various [Intel] controllers could be
|
|---|
| 288 | summarized like this (the term ATA as driver interface being a bit of our
|
|---|
| 289 | own invention):
|
|---|
| 290 |
|
|---|
| 291 | - Intel PIIX: IDE (I/O registers) and ATA (taskfile)
|
|---|
| 292 | - Intel ICH6: IDE (I/O registers), ATA (taskfile) and SATA
|
|---|
| 293 | (FIS, vendor-specific)
|
|---|
| 294 | - Intel ICH7: IDE (I/O registers), ATA (taskfile), SATA
|
|---|
| 295 | (FIS, vendor-specific) and AHCI (FIS)
|
|---|
| 296 | - Intel PCH: AHCI (FIS)
|
|---|
| 297 |
|
|---|
| 298 | Taskfiles are regions in memory with ATA commands which the IDE/ATA
|
|---|
| 299 | controller can read and process autonomously. FIS (Frame Information
|
|---|
| 300 | Structures) are pretty much the same but they are specific to the SATA
|
|---|
| 301 | communication protocol on the serial link. The most important FIS type
|
|---|
| 302 | for AHCI drivers is the H2D (host to device) FIS which basically contains
|
|---|
| 303 | the ATA command to be executed.
|
|---|
| 304 |
|
|---|
| 305 | The big advantage of AHCI controllers, apart from being vendor-neutral,
|
|---|
| 306 | is that they take care of a lot of things which previous-generation
|
|---|
| 307 | drivers like DANI1S506 would have to do step by step. For example, in
|
|---|
| 308 | order to send an ATAPI command, DANIS506 would have to do the following:
|
|---|
| 309 |
|
|---|
| 310 | * Send ATA "PACKET" command to device (via IDE registers, ATA taskfiles
|
|---|
| 311 | or SATA FIS)
|
|---|
| 312 | * Wait until device signals via interrupt it's ready for the ATAPI command
|
|---|
| 313 | * Send ATAPI command to device via PIO
|
|---|
| 314 | * Wait until device signals via interrupt it's ready to transfer data
|
|---|
| 315 | * Send/Receive any data that might come along with the ATAPI command via
|
|---|
| 316 | PIO, or wait for DMA transfer to complete
|
|---|
| 317 | * Wait until device signals via interrupt that command and data transfer
|
|---|
| 318 | have completed
|
|---|
| 319 |
|
|---|
| 320 | For OS2AHCI, the same operation looks like this:
|
|---|
| 321 |
|
|---|
| 322 | * Fill in AHCI command header, FIS with ATA "PACKET" command and the ATAPI
|
|---|
| 323 | command
|
|---|
| 324 | * Tell port engine to process the command
|
|---|
| 325 | * Wait until controller signals via interrupt that command and data
|
|---|
| 326 | transfer have completed
|
|---|
| 327 |
|
|---|
| 328 | The AHCI controller automatically takes care of all underlying bits and
|
|---|
| 329 | pieces. OS2AHCI doesn't even have to know whether a particular message is
|
|---|
| 330 | sent via PIO or DMA because this is handled by the AHCI controller, too.
|
|---|
| 331 | And the whole concept of PIO and DMA is only relevant between AHCI controller
|
|---|
| 332 | and the device -- all transfers between OS2AHCI and the AHCI controller are
|
|---|
| 333 | always done via DMA.
|
|---|
| 334 |
|
|---|
| 335 |
|
|---|
| 336 | SMART Support
|
|---|
| 337 | =============
|
|---|
| 338 |
|
|---|
| 339 | Starting with version 1.22, OS2AHCI supports the IOCTL interface required by
|
|---|
| 340 | existing SMART monitoring tools. Since those tools are hard-coded to open
|
|---|
| 341 | the character device named "IBMS506$", OS2AHCI will now register a device
|
|---|
| 342 | with this name, too.
|
|---|
| 343 |
|
|---|
| 344 | NOTES:
|
|---|
| 345 |
|
|---|
| 346 | - If multiple drivers exporting this character device name are loaded at
|
|---|
| 347 | the same time, the driver loaded last will receive all [SMART] requests.
|
|---|
| 348 | This means that if both DANIS506 and OS2AHCI are loaded and SMART support
|
|---|
| 349 | for OS2AHCI-controlled hard disks is desired, OS2AHCI will have to be
|
|---|
| 350 | loaded after DANIS506. It also means that DANIS506 may have to be told
|
|---|
| 351 | to ignore type 2 controllers (i.e. controllers supporting both SATA and
|
|---|
| 352 | AHCI) using the command line options "/A:x /I".
|
|---|
| 353 |
|
|---|
| 354 | - The IOCTL interface for SMART is based on the idea of IDE controllers
|
|---|
| 355 | with a master and a slave drive. OS2AHCI maps all devices (ATA or ATAPI)
|
|---|
| 356 | sequentially to this pattern. If, for example, you have 4 hard disks and
|
|---|
| 357 | one CDROM attached to a single controller on ports 1, 2, 5, 7, and 11,
|
|---|
| 358 | SMART tools will see 3 controllers as follows:
|
|---|
| 359 |
|
|---|
| 360 | - controller 0, master: HD on port 1
|
|---|
| 361 | - controller 0, slave: HD on port 2
|
|---|
| 362 | - controller 1, master: HD on port 5
|
|---|
| 363 | - controller 1, slave: HD on port 7
|
|---|
| 364 | - controller 2, master: CDROM on port 11
|
|---|
| 365 |
|
|---|
| 366 | - The DSKSP_GEN_GET_COUNTERS interface is currently unsupported; calls to
|
|---|
| 367 | the corresponding IOCTL will return 0 for all counters. SMART counters
|
|---|
| 368 | are not affected by this limitation, i.e. SMART tools will be able to
|
|---|
| 369 | report counters from the physical disk; this limitation only affects
|
|---|
| 370 | the software counters maintained by ADD drivers which do support the
|
|---|
| 371 | DSKSP_GEN_GET_COUNTERS IOCTL request.
|
|---|
| 372 |
|
|---|
