source: trunk/src/os2ahci/README@ 156

Last change on this file since 156 was 156, checked in by David Azarewicz, 13 years ago

debugging updates

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