| blob | 8d4623d877a2504c58b0ff9e96944d38b7e18680 |
1 .\" $NetBSD: wdc.9,v 1.15 2005/12/26 19:48:13 perry Exp $
2 .\"
3 .\" Copyright (c) 1998 Manuel Bouyer.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 .\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 .\"
25 .\"
26 .Dd October 18, 1998
27 .Dt WDC 9
28 .Os
29 .Sh NAME
30 .Nm wdc
31 .Nd machine-independent IDE/ATAPI driver
32 .Sh SYNOPSIS
33 .In dev/ata/atavar.h
34 .In sys/dev/ic/wdcvar.h
35 .Ft int
36 .Fn wdcprobe "struct channel_softc * chp"
37 .Ft void
38 .Fn wdcattach "struct channel_softc * chp"
39 .Sh DESCRIPTION
40 The
41 .Nm
42 driver provides the machine independent core functions for driving IDE
43 devices.
44 IDE devices-specific drivers
45 .Po
46 .Xr wd 4
47 or
48 .Xr atapibus 4
49 .Pc
50 will use services provided by
51 .Nm .
52 .Pp
53 The machine-dependent bus front-end provides informations to
54 .Nm
55 with the
56 .Va wdc_softc
57 and
58 .Va channel_softc
59 structures.
60 The first one defines global controller properties, and the second contains
61 per-channel informations.
62 .Nm
63 returns informations about the attached devices in the
64 .Va ata_drive_datas
65 structure.
66 .Bd -literal
67 struct wdc_softc { /* Per controller state */
68 struct device sc_dev;
69 int cap;
70 #define WDC_CAPABILITY_DATA16 0x0001
71 #define WDC_CAPABILITY_DATA32 0x0002
72 #define WDC_CAPABILITY_MODE 0x0004
73 #define WDC_CAPABILITY_DMA 0x0008
74 #define WDC_CAPABILITY_UDMA 0x0010
75 #define WDC_CAPABILITY_HWLOCK 0x0020
76 #define WDC_CAPABILITY_ATA_NOSTREAM 0x0040
77 #define WDC_CAPABILITY_ATAPI_NOSTREAM 0x0080
78 #define WDC_CAPABILITY_NO_EXTRA_RESETS 0x0100
79 #define WDC_CAPABILITY_PREATA 0x0200
80 #define WDC_CAPABILITY_IRQACK 0x0400
81 #define WDC_CAPABILITY_SINGLE_DRIVE 0x0800
82 #define WDC_CAPABILITY_NOIRQ 0x1000
83 #define WDC_CAPABILITY_SELECT 0x2000
84 uint8_t pio_mode;
85 uint8_t dma_mode;
86 int nchannels;
87 struct channel_softc *channels;
89 void *dma_arg;
90 int (*dma_init)(void *, int, int, void *, size_t, int);
91 void (*dma_start)(void *, int, int, int);
92 int (*dma_finish)(void *, int, int, int);
93 #define WDC_DMA_READ 0x01
94 #define WDC_DMA_POLL 0x02
96 int (*claim_hw)(void *, int);
97 void (*free_hw)(void *);
98 };
100 struct channel_softc { /* Per channel data */
101 int channel;
102 struct wdc_softc *wdc;
103 bus_space_tag_t cmd_iot;
104 bus_space_handle_t cmd_ioh;
105 bus_space_tag_t ctl_iot;
106 bus_space_handle_t ctl_ioh;
107 bus_space_tag_t data32iot;
108 bus_space_handle_t data32ioh;
109 int ch_flags;
110 #define WDCF_ACTIVE 0x01
111 #define WDCF_IRQ_WAIT 0x10
112 uint8_t ch_status;
113 uint8_t ch_error;
114 struct ata_drive_datas ch_drive[2];
115 struct channel_queue *ch_queue;
116 };
118 struct ata_drive_datas {
119 uint8_t drive;
120 uint8_t drive_flags;
121 #define DRIVE_ATA 0x01
122 #define DRIVE_ATAPI 0x02
123 #define DRIVE (DRIVE_ATA|DRIVE_ATAPI)
124 #define DRIVE_CAP32 0x04
125 #define DRIVE_DMA 0x08
126 #define DRIVE_UDMA 0x10
127 #define DRIVE_MODE 0x20
128 uint8_t PIO_mode;
129 uint8_t DMA_mode;
130 uint8_t UDMA_mode;
131 uint8_t state;
133 struct device *drv_softc;
134 void* chnl_softc;
135 };
136 .Ed
137 .Pp
138 The bus front-end needs to fill in the following elements of
139 .Va wdc_softc :
140 .Bl -tag -compact -width "dma_finish" -offset "xxxx"
141 .It cap
142 supports one or more of the WDC_CAPABILITY flags
143 .It nchannels
144 number of channels supported by this controller
145 .It channels
146 array of
147 .Va struct channel_softc
148 of size
149 .Va nchannels
150 properly initialised
151 .El
152 The following elements are optional:
153 .Bl -tag -compact -width "dma_finish" -offset "xxxx"
154 .It pio_mode
155 .It dma_mode
156 .It dma_arg
157 .It dma_init
158 .It dma_start
159 .It dma_finish
160 .It claim_hw
161 .It free_hw
162 .El
163 .Pp
164 The
165 .Va WDC_CAPABILITY_DATA16
166 and
167 .Va WDC_CAPABILITY_DATA32
168 flags informs
169 .Nm
170 whether the controller supports 16- or 32-bit I/O accesses on the data port.
171 If both are set, a test will be done for each drive using the ATA or
172 ATAPI IDENTIFY command, to automatically select the working mode.
173 .Pp
174 The
175 .Va WDC_CAPABILITY_DMA
176 and
177 .Va WDC_CAPABILITY_UDMA
178 flags are set for controllers supporting the DMA and Ultra-DMA modes.
179 The bus front-end needs to provide the
180 .Fn dma_init ,
181 .Fn dma_start
182 and
183 .Fn dma_finish
184 functions.
185 .Fn dma_init
186 is called just before issuing a DMA command to the IDE device.
187 The arguments are, respectively:
188 .Va dma_arg ,
189 the channel number, the drive number on this channel,
190 the virtual address of the DMA buffer, the size of the transfer, and the
191 .Va WDC_DMA
192 flags.
193 .Fn dma_start
194 is called just after issuing a DMA command to the IDE device.
195 The arguments are, respectively:
196 .Va dma_arg ,
197 the channel number, the drive number on this channel, and the
198 .Va WDC_DMA
199 flags.
200 .Fn dma_finish
201 is called once the transfer is complete.
202 The arguments are, respectively:
203 .Va dma_arg ,
204 the channel number, the drive number on this channel, and the
205 .Va WDC_DMA
206 flags.
207 .Va WDC_DMA_READ
208 indicates the direction of the data transfer, and
209 .Va WDC_DMA_POLL
210 indicates if the transfer will use (or used) interrupts.
211 .Pp
212 The
213 .Va WDC_CAPABILITY_MODE
214 flag means that the bus front-end can program the PIO and DMA modes, so
215 .Nm
216 needs to provide back the supported modes for each drive, and set the drives
217 modes.
218 The
219 .Va pio_mode
220 and
221 .Va dma_mode
222 needs to be set to the highest PIO and DMA mode supported.
223 If
224 .Va WDC_CAPABILITY_UDMA
225 is set, then
226 .Va dma_mode
227 must be set to the highest Ultra-DMA mode supported.
228 If
229 .Va WDC_CAPABILITY_MODE
230 is not set,
231 .Nm
232 will not attempt to change the current drive's settings, assuming the host's
233 firmware has done it right.
234 .Pp
235 The
236 .Va WDC_CAPABILITY_HWLOCK
237 flag is set for controllers needing hardware looking before accessing the
238 I/O ports.
239 If this flag is set, the bus front-end needs to provide the
240 .Fn claim_hw
241 and
242 .Fn free_hw
243 functions.
244 .Fn claim_hw
245 will be called when the driver wants to access the controller ports.
246 The second parameter is set to 1 when it is possible to sleep waiting
247 for the lock, 0 otherwise.
248 It should return 1 when access has been granted, 0 otherwise.
249 When access has not been granted and sleep is not allowed, the bus
250 front-end shall call
251 .Fn wdcrestart
252 with the first argument passed to
253 .Fn claim_hw
254 as argument.
255 This arguments will also be the one passed to
256 .Fn free_hw .
257 This function is called once the transfer is complete, so that the lock can
258 be released.
259 .Pp
260 Accesses to the data port are done by using the bus_space stream functions,
261 unless the
262 .Va WDC_CAPABILITY_ATA_NOSTREAM
263 or
264 .Va WDC_CAPABILITY_ATAPI_NOSTREAM
265 flags are set.
266 This should not be used, unless the data bus is not wired properly (which
267 seems common on big-endian systems), and byte-order needs to be preserved
268 for compatibility with the host's firmware.
269 Also note that the IDE bus is a little-endian bus, so the bus_space
270 functions used for the bus_space tag passed in the
271 .Va channel_softc
272 have to do the appropriate byte-swapping for big-endian systems.
273 .Pp
274 .Va WDC_CAPABILITY_NO_EXTRA_RESETS
275 avoid the controller reset at the end of the disks probe.
276 This reset is needed for some controllers, but causes problems with some
277 others.
278 .Pp
279 .Va WDC_CAPABILITY_NOIRQ
280 tells the driver that this controller doesn't have its interrupt lines
281 wired up usefully, so it should always use polled transfers.
282 .Pp
283 The bus front-end needs to fill in the following
284 elements of
285 .Va channel_softc :
286 .Bl -tag -compact -width "dma_finish" -offset "xxxx"
287 .It channel
288 The channel number on the controller
289 .It wdc
290 A pointer to the controller's wdc_softc
291 .It cmd_iot, cmd_ioh
292 Bus-space tag and handle for access to the command block registers (which
293 includes the 16-bit data port)
294 .It ctl_iot, ctl_ioh
295 Bus-space tag and handle for access to the control block registers
296 .It ch_queue
297 A pointer to a
298 .Va struct channel_queue .
299 This will hold the queues of outstanding commands for this controller.
300 .El
301 The following elements are optional:
302 .Bl -tag -compact -width "dma_finish" -offset "xxxx"
303 .It data32iot, data32ioh
304 Bus-space tag and handle for 32-bit data accesses.
305 Only needed if
306 .Va WDC_CAPABILITY_DATA32
307 is set in the controller's
308 .Va wdc_softc .
309 .El
310 .Pp
311 .Va ch_queue
312 can point to a common
313 .Va struct channel_queue
314 if the controller doesn't support concurrent access to its different channels.
315 If all channels are independent, it is recommended that each channel has
316 its own
317 .Va ch_queue
318 (for better performance).
319 .Pp
320 The bus-specific front-end can use the
321 .Fn wdcprobe
322 function, with a properly initialised
323 .Va struct channel_softc
324 as argument (
325 .Va wdc
326 can be set to NULL.
327 This allows
328 .Fn wdcprobe
329 to be easily used in bus front-end probe functions).
330 This function will return an integer where bit 0 will be set if the master
331 device has been found, and 1 if the slave device has been found.
332 .Pp
333 The bus-specific attach function has to call
334 .Fn wdcattach
335 for each channel, with a pointer to a properly initialised
336 .Va channel softc
337 as argument.
338 This will probe devices attached to the IDE channel and attach them.
339 Once this function returns, the
340 .Va ch_drive
341 array of the
342 .Va channel_softc
343 will contain the drive's capabilities.
344 This can be used to properly initialise the controller's mode, or disable a
345 channel without drives.
346 .Pp
347 The elements of interest in
348 .Va ata_drive_datas
349 for a bus front-end are:
350 .Bl -tag -compact -width "dma_finish" -offset "xxxx"
351 .It drive
352 The drive number
353 .It drive_flags
354 Flags indicating the drive capabilities.
355 A null
356 .Va drive_flags
357 indicate either that no drive is here, or that no driver was
358 found for this device.
359 .It PIO_mode, DMA_mode, UDMA_mode
360 the highest supported modes for this drive compatible with the controller's
361 capabilities.
362 Needs to be reset to the mode to use by the drive, if known.
363 .It drv_softc
364 A pointer to the drive's softc.
365 Can be used to print the drive's name.
366 .El
367 .Pp
368 .Va drive_flags
369 handles the following flags:
370 .Bl -tag -compact -width "dma_finish" -offset "xxxx"
371 .It DRIVE_ATA, DRIVE_ATAPI
372 Gives the drive type, if any.
373 The shortcut DRIVE can be used to just test the presence/absence of a drive.
374 .It DRIVE_CAP32
375 This drive works with 32-bit data I/O.
376 .It DRIVE_DMA
377 This drive supports DMA.
378 .It DRIVE_UDMA
379 This drive supports Ultra-DMA.
380 .It DRIVE_MODE
381 This drive properly reported its PIO and DMA mode.
382 .El
383 .Pp
384 Once the controller has been initialised, it has to reset the
385 .Va DRIVE_DMA
386 and
387 .Va DRIVE_UDMA ,
388 as well as the values of
389 .Va PIO_mode ,
390 .Va DMA_mode
391 and
392 .Va UDMA_mode
393 if the modes to be used are not highest ones supported by the drive.
394 .Sh SEE ALSO
395 .Xr wdc 4 ,
396 .Xr bus_space 9
397 .Sh CODE REFERENCES
398 The wdc core functions are implemented in
399 .Pa sys/dev/ic/wdc.c .
400 Low-level ATA and ATAPI support is provided by
401 .Pa sys/dev/ata_wdc.c
402 and
403 .Pa sys/dev/scsipi/atapi_wdc.c
404 respectively.
405 .Pp
406 An example of a simple bus front-end can be found in
407 .Pa sys/dev/isapnp/wdc_isapnp.c .
408 A more complex one, with multiple channels and bus-master DMA support is
409 .Pa sys/dev/pci/pciide.c .
410 .Pa sys/arch/atari/dev/wdc_mb.c
411 makes use of hardware locking, and also provides an example of bus-front
412 end for a big-endian system, which needs byte-swapping bus_space functions.