source: trunk/src/os2ahci/README@ 105

Last change on this file since 105 was 94, checked in by markus, 14 years ago

updated README (toolchain description)

File size: 10.9 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
60
61Watcom Build
62------------
63
64The source tree contains several files that were created during an
65attempt to use the Watcom compiler (e.g. wmakefile); however, the
66Watcom build is broken and produces a non-working driver.
67
68
69Installation
70============
71
72- Copy the driver file, OS2AHCI.ADD, to C:\OS2\BOOT
73
74- Add the following line to CONFIG.SYS:
75 BASEDEV=OS2AHCI.ADD
76
77
78Driver Command Line Options
79===========================
80
81Global Options
82
83Option Description
84------------------------------------------------------------------------------
85/c:<addr> Set debug COM port base address in hex (default = 3f8);
86 if used, this option should come before any /d options.
87/d Debug output on COM port; multiple "/d" options will
88 increase verbosity:
89 1 = requests
90 2 = detailed
91 3 = verbose, including MMIO operations
92/g:<vendor>:<device> Add generic PCI ID to list of supported AHCI adapters
93 (e.g. /g:8086:2829)
94/t Perform thorough PCI ID scan; default = on, can be
95 turned off with /!t to perform only a PCI class scan
96/r Reset ports during initialization (default = off
97 unless the [Intel] AHCI controller was found to be
98 initialized by the BIOS to SATA mode)
99/a Set adapter for adapter-specific options
100 (default = -1, all adapters)
101/p Set port for port-specific options
102 (default = -1, all ports)
103
104Adapter-specific Options
105
106Option Description
107------------------------------------------------------------------------------
108/i Ignore current adapter
109
110Port-specific Options
111
112Option Description
113------------------------------------------------------------------------------
114/s Enable SCSI emulation for ATAPI units (default = off)
115 SCSI emulation is required for tools like cdrecord.
116/n Enable NCQ (Native Command Queuing) for hard disks
117 (default = off)
118/ls Set link speed (default = 0):
119 0 = maximum,
120 1 = limit to generation 1
121 2 = limit to generation 2
122 3 = limit to generation 3
123/lp Set link power management (default = 0):
124 0 = full power management,
125 1 = transitions to "partial slumber state" disabled,
126 2 = transitions to "slumber state" disabled,
127 3 = transitions to both partial and slumber states
128 disabled
129/4 Force track size to be 56 sectors regardless of the
130 reported disk geometry to optimize partition boundaries
131 for hard disks with 4096 byte sectors.
132
133Port-specific options depend on the currently active adapter
134and port selector (/a and /p). Those selectors are -1 per default
135which means "all" adapters/ports. The scope can be reduced by limiting
136it to an adapter (/a) or an adapter and a port (/a and /p). The scope
137can be reset by setting the corresponding option back to -1.
138
139For example:
140
141 BASEDEV=OS2AHCI.ADD /n /a:0 /p:5 /!n /a:1 /p:-1 /!n
142
143This has the following effect:
144
145 - Enable NCQ for all hard disks
146 - Disable NCQ for hard disk on adapter #0, port #5
147 - Disable NCQ for all hard disks on adapter #1
148
149
150Native Command Queuing
151======================
152
153Native Command Queuing (NCQ) is a feature which allows sending multiple I/O
154requests to hard disks before waiting for any of the requests to complete,
155much like Tagged Command Queuing for SCSI devices. This allows the disks
156to reorder I/O requests to minimize head movements, resulting in improved
157performance when executing random I/Os. In practice, this will be most
158noticable when multiple programs request I/O services to different parts
159of the disk -- a single program typically won't queue up I/O's but instead
160will wait for each I/O to complete (with the exception of programs like
161database servers).
162
163While we believe NCQ will work with the majority of controllers and hard
164disks, it's currently turned off by default until we have more feedback
165from eComStation users. In order to turn on NCQ, just add the command line
166option "/n" to OS2AHCI.ADD.
167
168
169Interoperability With IDE Drivers
170=================================
171
172There are three kinds of IDE/ATA/SATA controllers:
173
174 1. Legacy controllers (IDE or SATA) without AHCI support
175 This kind of controller will only be recognized by IDE drivers
176 (IBM1S506.ADD or DANIS506.ADD).
177
178 2. AHCI-capable controllers which supports IDE/SATA legacy interfaces
179 This kind of controller will work with IDE or AHCI drivers and it's
180 up to the user to decide which driver to use.
181
182 3. AHCI-only controllers
183 This kind of controller will only be recognized by OS2AHCI.
184
185If there's a mix of controllers of types 1 and 3, both an IDE and an AHCI
186driver will be required.
187
188If type 2 controllers are involved, it's up to the user to decide which
189driver to use. Both DANIS506.ADD and OS2AHCI.ADD will verify whether another
190driver has already allocated the corresponding adapter, thus the only
191decision to take for mixed configurations is whether type-2 controllers
192should be handled by DANIS506.ADD or OS2AHCI.ADD and this can be done by
193having the desired driver's BASEDEV statement coming first in CONFIG.SYS.
194
195NOTE: Older versions of DANIS506.ADD did not verify whether the resources
196 of a particular adapter were already allocated by another driver.
197 DANIS506.ADD 1.8.8 or later is required for this to work.
198
199 When using earlier versions of DANI1S506.ADD, the options "/A:x /I"
200 will be required to tell DANI1S506.ADD to ignore adapters to be
201 driven by OS2AHCI.ADD. The same applies to IBM1S506.ADD
202
203Mixed Controller Example
204------------------------
205
206Assume a DELL D630 or a Thinkpad T60. The hard disk is attached to the
207SATA/AHCI controller of the ICH-7 hub while the CDROM is attached to the
208legacy PATA IDE controller. This allows two different configurations:
209
210 1. Drive HDD and CDROM via DANIS506.ADD
211 2. Drive HDD via OS2AHCI.ADD and CDROM via DANI1S506.ADD
212
213OS2AHCI.ADD can't drive the CDROM because it's attached to a legacy PATA
214IDE controller which doesn't support AHCI.
215
216 - If OS2AHCI.ADD comes first in CONFIG.SYS, it will take over the SATA/AHCI
217 controller and drive the HDD. DANIS506.ADD will take care of the PATA/IDE
218 controller for the CDROM.
219 - If DANIS506.ADD comes first in CONFIG.SYS, it will take over both the
220 SATA/AHCI and the PATA/IDE controller and OS2AHCI.ADD will silently exit.
221
222Advantages of AHCI
223------------------
224
225The interfaces provided by the various [Intel] controllers could be
226summarized like this (the term ATA as driver interface being a bit of our
227own invention):
228
229 - Intel PIIX: IDE (I/O registers) and ATA (taskfile)
230 - Intel ICH6: IDE (I/O registers), ATA (taskfile) and SATA
231 (FIS, vendor-specific)
232 - Intel ICH7: IDE (I/O registers), ATA (taskfile), SATA
233 (FIS, vendor-specific) and AHCI (FIS)
234 - Intel PCH: AHCI (FIS)
235
236Taskfiles are regions in memory with ATA commands which the IDE/ATA
237controller can read and process autonomously. FIS (Frame Information
238Structures) are pretty much the same but they are specific to the SATA
239communication protocol on the serial link. The most important FIS type
240for AHCI drivers is the H2D (host to device) FIS which basically contains
241the ATA command to be executed.
242
243The big advantage of AHCI controllers, apart from being vendor-neutral,
244is that they take care of a lot of things which previous-generation
245drivers like DANI1S506 would have to do step by step. For example, in
246order to send an ATAPI command, DANIS506 would have to do the following:
247
248 * Send ATA "PACKET" command to device (via IDE registers, ATA taskfiles
249 or SATA FIS)
250 * Wait until device signals via interrupt it's ready for the ATAPI command
251 * Send ATAPI command to device via PIO
252 * Wait until device signals via interrupt it's ready to transfer data
253 * Send/Receive any data that might come along with the ATAPI command via
254 PIO, or wait for DMA transfer to complete
255 * Wait until device signals via interrupt that command and data transfer
256 have completed
257
258For OS2AHCI, the same operation looks like this:
259
260 * Fill in AHCI command header, FIS with ATA "PACKET" command and the ATAPI
261 command
262 * Tell port engine to process the command
263 * Wait until controller signals via interrupt that command and data
264 transfer have completed
265
266The AHCI controller automatically takes care of all underlying bits and
267pieces. OS2AHCI doesn't even have to know whether a particular message is
268sent via PIO or DMA because this is handled by the AHCI controller, too.
269And the whole concept of PIO and DMA is only relevant between AHCI controller
270and the device -- all transfers between OS2AHCI and the AHCI controller are
271always done via DMA.
272
Note: See TracBrowser for help on using the repository browser.