source: trunk/src/os2ahci/README@ 144

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