source: trunk/src/os2ahci/README@ 162

Last change on this file since 162 was 162, checked in by David Azarewicz, 12 years ago

driver info updates, misc cleanup, add comments
This is version 1.28

File size: 17.4 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-2013 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
53Please note that builds other than the official binary delivered as
54part of eComStation releases or downloaded from ecomstation.nl are
55not officially supported by Mensys.
56
57
58Building The Driver
59-------------------
60
61The toolchain required for compilation consists of:
62
63 - IBM OS/2 DDK version 9.23 or later (see ddk\base\h\version.mak)
64 and that has been updated for SMP systems. (Used for include files)
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
72Define DDK and WATCOM in the environment.
73Use "wmake" or "wmake -a" to build the driver. See _build.cmd.
74
75Installation
76============
77
78- Run the included update.cmd,
79 or copy the driver file, OS2AHCI.ADD, to \OS2\BOOT on your boot disk.
80
81- Add the following line to CONFIG.SYS:
82 BASEDEV=OS2AHCI.ADD
83
84
85Driver Command Line Options
86===========================
87
88Global Options
89
90Option Description
91------------------------------------------------------------------------------
92/b:<baud> Initialize the COM port to the specified baud rate. Allowable
93 baud values are: 300, 600, 1200, 2400, 4800, 9600, 19200,
94 38400, 57600, and 115200. /b has no effect if /c is not also
95 specified. If /b is not specified, the COM port is not
96 initialized. For example, if you are using the kernel debugger,
97 the kernel debugger initializes the COM port so you should not
98 use this switch.
99
100/c:<n> Set debug COM port base address. Values for n can be:
101 1 = COM1
102 2 = COM2
103 a hex value (COM port base address) COM1=3f8, COM2=2f8
104 The default is 0. If set to 0 then no output goes to the COM port.
105
106/d[:n] Debug output to COM port/trace buffer. Values for n can be:
107 1 = requests
108 2 = detailed
109 3 = verbose, including MMIO operations
110 If :n is not specified the debug level is incremented for
111 each /d specified.
112
113/w Allows the trace buffer to wrap when full.
114
115/v[:n] Display informational messages during boot. Values for n can be:
116 1 = Display sign on banner
117 2 = Display adapter information
118 If :n is not specified the verbosity level is incremented for
119 each /v specified.
120
121/g:<vendor>:<device> Add generic PCI ID to list of supported AHCI adapters
122 (e.g. /g:8086:2829)
123
124/t Perform thorough PCI ID scan; default = on, can be
125 turned off with /!t to perform only a PCI class scan
126
127/f Force the use of the HW write cache when using NCQ
128 commands; see "Native Command Queuing" below for
129 further explanation (default = off)
130
131/r Reset ports during initialization (default = on)
132 Can be turned off with /!r, however, when the
133 [Intel] AHCI controller was found to be
134 initialized by the BIOS in SATA mode, ports will
135 always be reset even when /!r was specified
136
137/a:n Set adapter to n for adapter-specific options
138 (default = -1, all adapters)
139
140/p:n Set port to n for port-specific options
141 (default = -1, all ports)
142
143Adapter-specific Options
144
145Option Description
146------------------------------------------------------------------------------
147/i Ignore current adapter
148
149Port-specific Options
150
151Option Description
152------------------------------------------------------------------------------
153/s Enable SCSI emulation for ATAPI units (default = off)
154 SCSI emulation is required for tools like cdrecord.
155
156/n Enable NCQ (Native Command Queuing) for hard disks
157 (default = off)
158
159/ls Set link speed (default = 0):
160 0 = maximum,
161 1 = limit to generation 1
162 2 = limit to generation 2
163 3 = limit to generation 3
164
165/lp Set link power management (default = 0):
166 0 = full power management,
167 1 = transitions to "partial slumber state" disabled,
168 2 = transitions to "slumber state" disabled,
169 3 = transitions to both partial and slumber states disabled
170
171/4 Force track size to be 56 sectors regardless of the
172 reported disk geometry to optimize partition boundaries
173 for hard disks with 4096 byte sectors.
174
175Port-specific options depend on the currently active adapter
176and port selector (/a and /p). Those selectors are -1 per default
177which means "all" adapters/ports. The scope can be reduced by limiting
178it to an adapter (/a) or an adapter and a port (/a and /p). The scope
179can be reset by setting the corresponding option back to -1.
180
181For example:
182
183 BASEDEV=OS2AHCI.ADD /n /a:0 /p:5 /!n /a:1 /p:-1 /!n
184
185This has the following effect:
186
187 - Enable NCQ for all hard disks
188 - Disable NCQ for hard disk on adapter #0, port #5
189 - Disable NCQ for all hard disks on adapter #1
190
191
192Native Command Queuing
193======================
194
195Native Command Queuing (NCQ) is a feature which allows sending multiple I/O
196requests to hard disks before waiting for any of the requests to complete,
197much like Tagged Command Queuing for SCSI devices. This allows the disks
198to reorder I/O requests to minimize head movements, resulting in improved
199performance when executing random I/Os. In practice, this will be most
200noticable when multiple programs request I/O services to different parts
201of the disk -- a single program typically won't queue up I/O's but instead
202will wait for each I/O to complete (with the exception of programs like
203database servers).
204
205While we believe NCQ will work with the majority of controllers and hard
206disks, it's currently turned off by default until we have more feedback
207from eComStation users. In order to turn on NCQ, just add the command line
208option "/n" to OS2AHCI.ADD.
209
210NCQ and HW Caches
211-----------------
212
213In NCQ mode, OS2AHCI supports a request flag which allows upstream code
214(e.g. file systems) to force writes to go directly to the disk instead
215of being buffered in the HW disk cache. However, at least JFS doesn't
216support this flag properly which effectively disables the HW disk cache
217for write operations across the board, resulting in a substantial
218performance loss. In order to prevent OS2AHCI from disabling the HW
219cache when so requested by upstream code, please use the command line
220option "/f".
221
222This may, of course, result in data loss in case of power failures but
223apparently this was the situation with previous IDE drivers as well thus
224shouldn't make much difference in the field. The JFS code also seems to
225imply that this flag has never been widely supported by [IDE] drivers;
226otherwise, the JFS developers should have stumbled over the performance
227loss a long time ago and fixed the code.
228
229NOTES:
230
231 - Without NCQ, OS2AHCI behaves like former IDE drivers, i.e. the HW
232 cache will always be enabled (on modern disks).
233
234 - When suspending, rebooting or shutting down, OS2AHCI always flushes
235 the HW disk cache regardless of the "/f" or "/n" command line options.
236
237
238Interoperability With IDE Drivers
239=================================
240
241There are three kinds of IDE/ATA/SATA controllers:
242
243 1. Legacy controllers (IDE or SATA) without AHCI support
244 This kind of controller will only be recognized by IDE drivers
245 (IBM1S506.ADD or DANIS506.ADD).
246
247 2. AHCI-capable controllers which supports IDE/SATA legacy interfaces
248 This kind of controller will work with IDE or AHCI drivers and it's
249 up to the user to decide which driver to use.
250
251 3. AHCI-only controllers
252 This kind of controller will only be recognized by OS2AHCI.
253
254If there's a mix of controllers of types 1 and 3, both an IDE and an AHCI
255driver will be required.
256
257If type 2 controllers are involved, it's up to the user to decide which
258driver to use. Both DANIS506.ADD and OS2AHCI.ADD will verify whether another
259driver has already allocated the corresponding adapter, thus the only
260decision to take for mixed configurations is whether type-2 controllers
261should be handled by DANIS506.ADD or OS2AHCI.ADD and this can be done by
262having the desired driver's BASEDEV statement coming first in CONFIG.SYS.
263
264NOTE: Older versions of DANIS506.ADD did not verify whether the resources
265 of a particular adapter were already allocated by another driver.
266 DANIS506.ADD 1.8.8 or later is required for this to work.
267
268 When using earlier versions of DANI1S506.ADD, the options "/A:x /I"
269 will be required to tell DANI1S506.ADD to ignore adapters to be
270 driven by OS2AHCI.ADD. The same applies to IBM1S506.ADD
271
272Mixed Controller Example
273------------------------
274
275Assume a DELL D630 or a Thinkpad T60. The hard disk is attached to the
276SATA/AHCI controller of the ICH-7 hub while the CDROM is attached to the
277legacy PATA IDE controller. This allows two different configurations:
278
279 1. Drive HDD and CDROM via DANIS506.ADD
280 2. Drive HDD via OS2AHCI.ADD and CDROM via DANI1S506.ADD
281
282OS2AHCI.ADD can't drive the CDROM because it's attached to a legacy PATA
283IDE controller which doesn't support AHCI.
284
285 - If OS2AHCI.ADD comes first in CONFIG.SYS, it will take over the SATA/AHCI
286 controller and drive the HDD. DANIS506.ADD will take care of the PATA/IDE
287 controller for the CDROM.
288 - If DANIS506.ADD comes first in CONFIG.SYS, it will take over both the
289 SATA/AHCI and the PATA/IDE controller and OS2AHCI.ADD will silently exit.
290
291Advantages of AHCI
292------------------
293
294The interfaces provided by the various [Intel] controllers could be
295summarized like this (the term ATA as driver interface being a bit of our
296own invention):
297
298 - Intel PIIX: IDE (I/O registers) and ATA (taskfile)
299 - Intel ICH6: IDE (I/O registers), ATA (taskfile) and SATA
300 (FIS, vendor-specific)
301 - Intel ICH7: IDE (I/O registers), ATA (taskfile), SATA
302 (FIS, vendor-specific) and AHCI (FIS)
303 - Intel PCH: AHCI (FIS)
304
305Taskfiles are regions in memory with ATA commands which the IDE/ATA
306controller can read and process autonomously. FIS (Frame Information
307Structures) are pretty much the same but they are specific to the SATA
308communication protocol on the serial link. The most important FIS type
309for AHCI drivers is the H2D (host to device) FIS which basically contains
310the ATA command to be executed.
311
312The big advantage of AHCI controllers, apart from being vendor-neutral,
313is that they take care of a lot of things which previous-generation
314drivers like DANI1S506 would have to do step by step. For example, in
315order to send an ATAPI command, DANIS506 would have to do the following:
316
317 * Send ATA "PACKET" command to device (via IDE registers, ATA taskfiles
318 or SATA FIS)
319 * Wait until device signals via interrupt it's ready for the ATAPI command
320 * Send ATAPI command to device via PIO
321 * Wait until device signals via interrupt it's ready to transfer data
322 * Send/Receive any data that might come along with the ATAPI command via
323 PIO, or wait for DMA transfer to complete
324 * Wait until device signals via interrupt that command and data transfer
325 have completed
326
327For OS2AHCI, the same operation looks like this:
328
329 * Fill in AHCI command header, FIS with ATA "PACKET" command and the ATAPI
330 command
331 * Tell port engine to process the command
332 * Wait until controller signals via interrupt that command and data
333 transfer have completed
334
335The AHCI controller automatically takes care of all underlying bits and
336pieces. OS2AHCI doesn't even have to know whether a particular message is
337sent via PIO or DMA because this is handled by the AHCI controller, too.
338And the whole concept of PIO and DMA is only relevant between AHCI controller
339and the device -- all transfers between OS2AHCI and the AHCI controller are
340always done via DMA.
341
342
343SMART Support
344=============
345
346Starting with version 1.22, OS2AHCI supports the IOCTL interface required by
347existing SMART monitoring tools. Since those tools are hard-coded to open
348the character device named "IBMS506$", OS2AHCI will now register a device
349with this name, too.
350
351NOTES:
352
353 - If multiple drivers exporting this character device name are loaded at
354 the same time, the driver loaded last will receive all [SMART] requests.
355 This means that if both DANIS506 and OS2AHCI are loaded and SMART support
356 for OS2AHCI-controlled hard disks is desired, OS2AHCI will have to be
357 loaded after DANIS506. It also means that DANIS506 may have to be told
358 to ignore type 2 controllers (i.e. controllers supporting both SATA and
359 AHCI) using the command line options "/A:x /I".
360
361 - The IOCTL interface for SMART is based on the idea of IDE controllers
362 with a master and a slave drive. OS2AHCI maps all devices (ATA or ATAPI)
363 sequentially to this pattern. If, for example, you have 4 hard disks and
364 one CDROM attached to a single controller on ports 1, 2, 5, 7, and 11,
365 SMART tools will see 3 controllers as follows:
366
367 - controller 0, master: HD on port 1
368 - controller 0, slave: HD on port 2
369 - controller 1, master: HD on port 5
370 - controller 1, slave: HD on port 7
371 - controller 2, master: CDROM on port 11
372
373 - The DSKSP_GEN_GET_COUNTERS interface is currently unsupported; calls to
374 the corresponding IOCTL will return 0 for all counters. SMART counters
375 are not affected by this limitation, i.e. SMART tools will be able to
376 report counters from the physical disk; this limitation only affects
377 the software counters maintained by ADD drivers which do support the
378 DSKSP_GEN_GET_COUNTERS IOCTL request.
379
380
381Change Log
382==========
383
384v.1.28 01-Jun-2013 - David Azarewicz
385 Reworked trap dump kernel exit
386 Removed unused IDC entry point.
387 Reworked suspend/resume routines.
388 Implemented a temporary hack to make resume work reasonably well.
389 Suspend/resume is only supported on eCS systems with ACPI.
390 Suspend/resume is known to not work reliably and cannot be further
391 addressed in this driver.
392
393v.1.27 23-Apr-2013 - David Azarewicz
394 Added LVM aware disk geometry reporting.
395 Begin to add disk information report - not finished yet.
396 Removed undocumented /q switch and made the driver quiet by default.
397 Debug output improvements.
398 Added /b switch for setting debug baud rate.
399 Fixed up time delay functions
400
401v.1.26 26-Mar-2013 - David Azarewicz
402 Fix spin-up / power-up issue on some hardware
403 Reorganized and improved debug output.
404
405v.1.26 21-Feb-2013 - rousseau
406 Virtual box fix
407 Some SMP fixes
408 Changed default for port reset to always
409
410v.1.25 02-Oct-2012 - markus.thi
411 Added support for trap dumps
412
413v.1.24 21-May-2012 - markus.thi
414 Fixed JFS long format hang (ticket 16)
415
416V.1.23 16-May-2012 - markus.thi
417 added IDC entry point to allow switching back to BIOS mode
418
419v.1.22 17-Oct-2011 - markus.thi
420 Added "IBMS506" header to accomodate broken SMART tools.
Note: See TracBrowser for help on using the repository browser.