1 ======================== 1 ========================
2 libATA Developer's Guide 2 libATA Developer's Guide
3 ======================== 3 ========================
4 4
5 :Author: Jeff Garzik 5 :Author: Jeff Garzik
6 6
7 Introduction 7 Introduction
8 ============ 8 ============
9 9
10 libATA is a library used inside the Linux kern 10 libATA is a library used inside the Linux kernel to support ATA host
11 controllers and devices. libATA provides an AT 11 controllers and devices. libATA provides an ATA driver API, class
12 transports for ATA and ATAPI devices, and SCSI 12 transports for ATA and ATAPI devices, and SCSI<->ATA translation for ATA
13 devices according to the T10 SAT specification 13 devices according to the T10 SAT specification.
14 14
15 This Guide documents the libATA driver API, li 15 This Guide documents the libATA driver API, library functions, library
16 internals, and a couple sample ATA low-level d 16 internals, and a couple sample ATA low-level drivers.
17 17
18 libata Driver API 18 libata Driver API
19 ================= 19 =================
20 20
21 :c:type:`struct ata_port_operations <ata_port_ 21 :c:type:`struct ata_port_operations <ata_port_operations>`
22 is defined for every low-level libata 22 is defined for every low-level libata
23 hardware driver, and it controls how the low-l 23 hardware driver, and it controls how the low-level driver interfaces
24 with the ATA and SCSI layers. 24 with the ATA and SCSI layers.
25 25
26 FIS-based drivers will hook into the system wi 26 FIS-based drivers will hook into the system with ``->qc_prep()`` and
27 ``->qc_issue()`` high-level hooks. Hardware wh 27 ``->qc_issue()`` high-level hooks. Hardware which behaves in a manner
28 similar to PCI IDE hardware may utilize severa 28 similar to PCI IDE hardware may utilize several generic helpers,
29 defining at a bare minimum the bus I/O address 29 defining at a bare minimum the bus I/O addresses of the ATA shadow
30 register blocks. 30 register blocks.
31 31
32 :c:type:`struct ata_port_operations <ata_port_ 32 :c:type:`struct ata_port_operations <ata_port_operations>`
33 ---------------------------------------------- 33 ----------------------------------------------------------
34 34
35 Post-IDENTIFY device configuration 35 Post-IDENTIFY device configuration
36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37 37
38 :: 38 ::
39 39
40 void (*dev_config) (struct ata_port *, str 40 void (*dev_config) (struct ata_port *, struct ata_device *);
41 41
42 42
43 Called after IDENTIFY [PACKET] DEVICE is issue 43 Called after IDENTIFY [PACKET] DEVICE is issued to each device found.
44 Typically used to apply device-specific fixups 44 Typically used to apply device-specific fixups prior to issue of SET
45 FEATURES - XFER MODE, and prior to operation. 45 FEATURES - XFER MODE, and prior to operation.
46 46
47 This entry may be specified as NULL in ata_por 47 This entry may be specified as NULL in ata_port_operations.
48 48
49 Set PIO/DMA mode 49 Set PIO/DMA mode
50 ~~~~~~~~~~~~~~~~ 50 ~~~~~~~~~~~~~~~~
51 51
52 :: 52 ::
53 53
54 void (*set_piomode) (struct ata_port *, st 54 void (*set_piomode) (struct ata_port *, struct ata_device *);
55 void (*set_dmamode) (struct ata_port *, st 55 void (*set_dmamode) (struct ata_port *, struct ata_device *);
56 void (*post_set_mode) (struct ata_port *); 56 void (*post_set_mode) (struct ata_port *);
57 unsigned int (*mode_filter) (struct ata_po 57 unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);
58 58
59 59
60 Hooks called prior to the issue of SET FEATURE 60 Hooks called prior to the issue of SET FEATURES - XFER MODE command. The
61 optional ``->mode_filter()`` hook is called wh 61 optional ``->mode_filter()`` hook is called when libata has built a mask of
62 the possible modes. This is passed to the ``-> 62 the possible modes. This is passed to the ``->mode_filter()`` function
63 which should return a mask of valid modes afte 63 which should return a mask of valid modes after filtering those
64 unsuitable due to hardware limits. It is not v 64 unsuitable due to hardware limits. It is not valid to use this interface
65 to add modes. 65 to add modes.
66 66
67 ``dev->pio_mode`` and ``dev->dma_mode`` are gu 67 ``dev->pio_mode`` and ``dev->dma_mode`` are guaranteed to be valid when
68 ``->set_piomode()`` and when ``->set_dmamode() 68 ``->set_piomode()`` and when ``->set_dmamode()`` is called. The timings for
69 any other drive sharing the cable will also be 69 any other drive sharing the cable will also be valid at this point. That
70 is the library records the decisions for the m 70 is the library records the decisions for the modes of each drive on a
71 channel before it attempts to set any of them. 71 channel before it attempts to set any of them.
72 72
73 ``->post_set_mode()`` is called unconditionall 73 ``->post_set_mode()`` is called unconditionally, after the SET FEATURES -
74 XFER MODE command completes successfully. 74 XFER MODE command completes successfully.
75 75
76 ``->set_piomode()`` is always called (if prese 76 ``->set_piomode()`` is always called (if present), but ``->set_dma_mode()``
77 is only called if DMA is possible. 77 is only called if DMA is possible.
78 78
79 Taskfile read/write 79 Taskfile read/write
80 ~~~~~~~~~~~~~~~~~~~ 80 ~~~~~~~~~~~~~~~~~~~
81 81
82 :: 82 ::
83 83
84 void (*sff_tf_load) (struct ata_port *ap, 84 void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
85 void (*sff_tf_read) (struct ata_port *ap, 85 void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
86 86
87 87
88 ``->tf_load()`` is called to load the given ta 88 ``->tf_load()`` is called to load the given taskfile into hardware
89 registers / DMA buffers. ``->tf_read()`` is ca 89 registers / DMA buffers. ``->tf_read()`` is called to read the hardware
90 registers / DMA buffers, to obtain the current 90 registers / DMA buffers, to obtain the current set of taskfile register
91 values. Most drivers for taskfile-based hardwa 91 values. Most drivers for taskfile-based hardware (PIO or MMIO) use
92 :c:func:`ata_sff_tf_load` and :c:func:`ata_sff 92 :c:func:`ata_sff_tf_load` and :c:func:`ata_sff_tf_read` for these hooks.
93 93
94 PIO data read/write 94 PIO data read/write
95 ~~~~~~~~~~~~~~~~~~~ 95 ~~~~~~~~~~~~~~~~~~~
96 96
97 :: 97 ::
98 98
99 void (*sff_data_xfer) (struct ata_device * 99 void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
100 100
101 101
102 All bmdma-style drivers must implement this ho 102 All bmdma-style drivers must implement this hook. This is the low-level
103 operation that actually copies the data bytes 103 operation that actually copies the data bytes during a PIO data
104 transfer. Typically the driver will choose one 104 transfer. Typically the driver will choose one of
105 :c:func:`ata_sff_data_xfer`, or :c:func:`ata_s 105 :c:func:`ata_sff_data_xfer`, or :c:func:`ata_sff_data_xfer32`.
106 106
107 ATA command execute 107 ATA command execute
108 ~~~~~~~~~~~~~~~~~~~ 108 ~~~~~~~~~~~~~~~~~~~
109 109
110 :: 110 ::
111 111
112 void (*sff_exec_command)(struct ata_port * 112 void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
113 113
114 114
115 causes an ATA command, previously loaded with 115 causes an ATA command, previously loaded with ``->tf_load()``, to be
116 initiated in hardware. Most drivers for taskfi 116 initiated in hardware. Most drivers for taskfile-based hardware use
117 :c:func:`ata_sff_exec_command` for this hook. 117 :c:func:`ata_sff_exec_command` for this hook.
118 118
119 Per-cmd ATAPI DMA capabilities filter 119 Per-cmd ATAPI DMA capabilities filter
120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121 121
122 :: 122 ::
123 123
124 int (*check_atapi_dma) (struct ata_queued_ 124 int (*check_atapi_dma) (struct ata_queued_cmd *qc);
125 125
126 126
127 Allow low-level driver to filter ATA PACKET co 127 Allow low-level driver to filter ATA PACKET commands, returning a status
128 indicating whether or not it is OK to use DMA 128 indicating whether or not it is OK to use DMA for the supplied PACKET
129 command. 129 command.
130 130
131 This hook may be specified as NULL, in which c 131 This hook may be specified as NULL, in which case libata will assume
132 that atapi dma can be supported. 132 that atapi dma can be supported.
133 133
134 Read specific ATA shadow registers 134 Read specific ATA shadow registers
135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136 136
137 :: 137 ::
138 138
139 u8 (*sff_check_status)(struct ata_port * 139 u8 (*sff_check_status)(struct ata_port *ap);
140 u8 (*sff_check_altstatus)(struct ata_por 140 u8 (*sff_check_altstatus)(struct ata_port *ap);
141 141
142 142
143 Reads the Status/AltStatus ATA shadow register 143 Reads the Status/AltStatus ATA shadow register from hardware. On some
144 hardware, reading the Status register has the 144 hardware, reading the Status register has the side effect of clearing
145 the interrupt condition. Most drivers for task 145 the interrupt condition. Most drivers for taskfile-based hardware use
146 :c:func:`ata_sff_check_status` for this hook. 146 :c:func:`ata_sff_check_status` for this hook.
147 147
148 Write specific ATA shadow register 148 Write specific ATA shadow register
149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
150 150
151 :: 151 ::
152 152
153 void (*sff_set_devctl)(struct ata_port *ap 153 void (*sff_set_devctl)(struct ata_port *ap, u8 ctl);
154 154
155 155
156 Write the device control ATA shadow register t 156 Write the device control ATA shadow register to the hardware. Most
157 drivers don't need to define this. 157 drivers don't need to define this.
158 158
159 Select ATA device on bus 159 Select ATA device on bus
160 ~~~~~~~~~~~~~~~~~~~~~~~~ 160 ~~~~~~~~~~~~~~~~~~~~~~~~
161 161
162 :: 162 ::
163 163
164 void (*sff_dev_select)(struct ata_port *ap 164 void (*sff_dev_select)(struct ata_port *ap, unsigned int device);
165 165
166 166
167 Issues the low-level hardware command(s) that 167 Issues the low-level hardware command(s) that causes one of N hardware
168 devices to be considered 'selected' (active an 168 devices to be considered 'selected' (active and available for use) on
169 the ATA bus. This generally has no meaning on 169 the ATA bus. This generally has no meaning on FIS-based devices.
170 170
171 Most drivers for taskfile-based hardware use : 171 Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for
172 this hook. 172 this hook.
173 173
174 Private tuning method 174 Private tuning method
175 ~~~~~~~~~~~~~~~~~~~~~ 175 ~~~~~~~~~~~~~~~~~~~~~
176 176
177 :: 177 ::
178 178
179 void (*set_mode) (struct ata_port *ap); 179 void (*set_mode) (struct ata_port *ap);
180 180
181 181
182 By default libata performs drive and controlle 182 By default libata performs drive and controller tuning in accordance
183 with the ATA timing rules and also applies bla 183 with the ATA timing rules and also applies blacklists and cable limits.
184 Some controllers need special handling and hav 184 Some controllers need special handling and have custom tuning rules,
185 typically raid controllers that use ATA comman 185 typically raid controllers that use ATA commands but do not actually do
186 drive timing. 186 drive timing.
187 187
188 **Warning** 188 **Warning**
189 189
190 This hook should not be used to replace th 190 This hook should not be used to replace the standard controller
191 tuning logic when a controller has quirks. 191 tuning logic when a controller has quirks. Replacing the default
192 tuning logic in that case would bypass han 192 tuning logic in that case would bypass handling for drive and bridge
193 quirks that may be important to data relia 193 quirks that may be important to data reliability. If a controller
194 needs to filter the mode selection it shou 194 needs to filter the mode selection it should use the mode_filter
195 hook instead. 195 hook instead.
196 196
197 Control PCI IDE BMDMA engine 197 Control PCI IDE BMDMA engine
198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199 199
200 :: 200 ::
201 201
202 void (*bmdma_setup) (struct ata_queued_cmd 202 void (*bmdma_setup) (struct ata_queued_cmd *qc);
203 void (*bmdma_start) (struct ata_queued_cmd 203 void (*bmdma_start) (struct ata_queued_cmd *qc);
204 void (*bmdma_stop) (struct ata_port *ap); 204 void (*bmdma_stop) (struct ata_port *ap);
205 u8 (*bmdma_status) (struct ata_port *ap) 205 u8 (*bmdma_status) (struct ata_port *ap);
206 206
207 207
208 When setting up an IDE BMDMA transaction, thes 208 When setting up an IDE BMDMA transaction, these hooks arm
209 (``->bmdma_setup``), fire (``->bmdma_start``), 209 (``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the
210 hardware's DMA engine. ``->bmdma_status`` is u 210 hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI
211 IDE DMA Status register. 211 IDE DMA Status register.
212 212
213 These hooks are typically either no-ops, or si 213 These hooks are typically either no-ops, or simply not implemented, in
214 FIS-based drivers. 214 FIS-based drivers.
215 215
216 Most legacy IDE drivers use :c:func:`ata_bmdma 216 Most legacy IDE drivers use :c:func:`ata_bmdma_setup` for the
217 :c:func:`bmdma_setup` hook. :c:func:`ata_bmdma 217 :c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointer
218 to the PRD table to the IDE PRD Table Address 218 to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA
219 Command register, and call :c:func:`exec_comma 219 Command register, and call :c:func:`exec_command` to begin the transfer.
220 220
221 Most legacy IDE drivers use :c:func:`ata_bmdma 221 Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the
222 :c:func:`bmdma_start` hook. :c:func:`ata_bmdma 222 :c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write the
223 ATA_DMA_START flag to the DMA Command register 223 ATA_DMA_START flag to the DMA Command register.
224 224
225 Many legacy IDE drivers use :c:func:`ata_bmdma 225 Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the
226 :c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_ 226 :c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_START
227 flag in the DMA command register. 227 flag in the DMA command register.
228 228
229 Many legacy IDE drivers use :c:func:`ata_bmdma 229 Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the
230 :c:func:`bmdma_status` hook. 230 :c:func:`bmdma_status` hook.
231 231
232 High-level taskfile hooks 232 High-level taskfile hooks
233 ~~~~~~~~~~~~~~~~~~~~~~~~~ 233 ~~~~~~~~~~~~~~~~~~~~~~~~~
234 234
235 :: 235 ::
236 236
237 enum ata_completion_errors (*qc_prep) (str 237 enum ata_completion_errors (*qc_prep) (struct ata_queued_cmd *qc);
238 int (*qc_issue) (struct ata_queued_cmd *qc 238 int (*qc_issue) (struct ata_queued_cmd *qc);
239 239
240 240
241 Higher-level hooks, these two hooks can potent 241 Higher-level hooks, these two hooks can potentially supersede several of
242 the above taskfile/DMA engine hooks. ``->qc_pr 242 the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the
243 buffers have been DMA-mapped, and is typically 243 buffers have been DMA-mapped, and is typically used to populate the
244 hardware's DMA scatter-gather table. Some driv 244 hardware's DMA scatter-gather table. Some drivers use the standard
245 :c:func:`ata_bmdma_qc_prep` and :c:func:`ata_b 245 :c:func:`ata_bmdma_qc_prep` and :c:func:`ata_bmdma_dumb_qc_prep` helper
246 functions, but more advanced drivers roll thei 246 functions, but more advanced drivers roll their own.
247 247
248 ``->qc_issue`` is used to make a command activ 248 ``->qc_issue`` is used to make a command active, once the hardware and S/G
249 tables have been prepared. IDE BMDMA drivers u 249 tables have been prepared. IDE BMDMA drivers use the helper function
250 :c:func:`ata_sff_qc_issue` for taskfile protoc 250 :c:func:`ata_sff_qc_issue` for taskfile protocol-based dispatch. More
251 advanced drivers implement their own ``->qc_is 251 advanced drivers implement their own ``->qc_issue``.
252 252
253 :c:func:`ata_sff_qc_issue` calls ``->sff_tf_lo 253 :c:func:`ata_sff_qc_issue` calls ``->sff_tf_load()``, ``->bmdma_setup()``, and
254 ``->bmdma_start()`` as necessary to initiate a 254 ``->bmdma_start()`` as necessary to initiate a transfer.
255 255
256 Exception and probe handling (EH) 256 Exception and probe handling (EH)
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258 258
259 :: 259 ::
260 260
261 void (*freeze) (struct ata_port *ap); 261 void (*freeze) (struct ata_port *ap);
262 void (*thaw) (struct ata_port *ap); 262 void (*thaw) (struct ata_port *ap);
263 263
264 264
265 :c:func:`ata_port_freeze` is called when HSM v 265 :c:func:`ata_port_freeze` is called when HSM violations or some other
266 condition disrupts normal operation of the por 266 condition disrupts normal operation of the port. A frozen port is not
267 allowed to perform any operation until the por 267 allowed to perform any operation until the port is thawed, which usually
268 follows a successful reset. 268 follows a successful reset.
269 269
270 The optional ``->freeze()`` callback can be us 270 The optional ``->freeze()`` callback can be used for freezing the port
271 hardware-wise (e.g. mask interrupt and stop DM 271 hardware-wise (e.g. mask interrupt and stop DMA engine). If a port
272 cannot be frozen hardware-wise, the interrupt 272 cannot be frozen hardware-wise, the interrupt handler must ack and clear
273 interrupts unconditionally while the port is f 273 interrupts unconditionally while the port is frozen.
274 274
275 The optional ``->thaw()`` callback is called t 275 The optional ``->thaw()`` callback is called to perform the opposite of
276 ``->freeze()``: prepare the port for normal op 276 ``->freeze()``: prepare the port for normal operation once again. Unmask
277 interrupts, start DMA engine, etc. 277 interrupts, start DMA engine, etc.
278 278
279 :: 279 ::
280 280
281 void (*error_handler) (struct ata_port *ap 281 void (*error_handler) (struct ata_port *ap);
282 282
283 283
284 ``->error_handler()`` is a driver's hook into 284 ``->error_handler()`` is a driver's hook into probe, hotplug, and recovery
285 and other exceptional conditions. The primary 285 and other exceptional conditions. The primary responsibility of an
286 implementation is to call :c:func:`ata_do_eh` 286 implementation is to call :c:func:`ata_do_eh` or :c:func:`ata_bmdma_drive_eh`
287 with a set of EH hooks as arguments: 287 with a set of EH hooks as arguments:
288 288
289 'prereset' hook (may be NULL) is called during 289 'prereset' hook (may be NULL) is called during an EH reset, before any
290 other actions are taken. 290 other actions are taken.
291 291
292 'postreset' hook (may be NULL) is called after 292 'postreset' hook (may be NULL) is called after the EH reset is
293 performed. Based on existing conditions, sever 293 performed. Based on existing conditions, severity of the problem, and
294 hardware capabilities, 294 hardware capabilities,
295 295
296 Either 'softreset' (may be NULL) or 'hardreset 296 Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
297 called to perform the low-level EH reset. 297 called to perform the low-level EH reset.
298 298
299 :: 299 ::
300 300
301 void (*post_internal_cmd) (struct ata_queu 301 void (*post_internal_cmd) (struct ata_queued_cmd *qc);
302 302
303 303
304 Perform any hardware-specific actions necessar 304 Perform any hardware-specific actions necessary to finish processing
305 after executing a probe-time or EH-time comman 305 after executing a probe-time or EH-time command via
306 :c:func:`ata_exec_internal`. 306 :c:func:`ata_exec_internal`.
307 307
308 Hardware interrupt handling 308 Hardware interrupt handling
309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
310 310
311 :: 311 ::
312 312
313 irqreturn_t (*irq_handler)(int, void *, st 313 irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
314 void (*irq_clear) (struct ata_port *); 314 void (*irq_clear) (struct ata_port *);
315 315
316 316
317 ``->irq_handler`` is the interrupt handling ro 317 ``->irq_handler`` is the interrupt handling routine registered with the
318 system, by libata. ``->irq_clear`` is called d 318 system, by libata. ``->irq_clear`` is called during probe just before the
319 interrupt handler is registered, to be sure ha 319 interrupt handler is registered, to be sure hardware is quiet.
320 320
321 The second argument, dev_instance, should be c 321 The second argument, dev_instance, should be cast to a pointer to
322 :c:type:`struct ata_host_set <ata_host_set>`. 322 :c:type:`struct ata_host_set <ata_host_set>`.
323 323
324 Most legacy IDE drivers use :c:func:`ata_sff_i 324 Most legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler
325 hook, which scans all ports in the host_set, d 325 hook, which scans all ports in the host_set, determines which queued
326 command was active (if any), and calls ata_sff 326 command was active (if any), and calls ata_sff_host_intr(ap,qc).
327 327
328 Most legacy IDE drivers use :c:func:`ata_sff_i 328 Most legacy IDE drivers use :c:func:`ata_sff_irq_clear` for the
329 :c:func:`irq_clear` hook, which simply clears 329 :c:func:`irq_clear` hook, which simply clears the interrupt and error flags
330 in the DMA status register. 330 in the DMA status register.
331 331
332 SATA phy read/write 332 SATA phy read/write
333 ~~~~~~~~~~~~~~~~~~~ 333 ~~~~~~~~~~~~~~~~~~~
334 334
335 :: 335 ::
336 336
337 int (*scr_read) (struct ata_port *ap, unsi 337 int (*scr_read) (struct ata_port *ap, unsigned int sc_reg,
338 u32 *val); 338 u32 *val);
339 int (*scr_write) (struct ata_port *ap, uns 339 int (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
340 u32 val); 340 u32 val);
341 341
342 342
343 Read and write standard SATA phy registers. 343 Read and write standard SATA phy registers.
344 sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ 344 sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
345 345
346 Init and shutdown 346 Init and shutdown
347 ~~~~~~~~~~~~~~~~~ 347 ~~~~~~~~~~~~~~~~~
348 348
349 :: 349 ::
350 350
351 int (*port_start) (struct ata_port *ap); 351 int (*port_start) (struct ata_port *ap);
352 void (*port_stop) (struct ata_port *ap); 352 void (*port_stop) (struct ata_port *ap);
353 void (*host_stop) (struct ata_host_set *ho 353 void (*host_stop) (struct ata_host_set *host_set);
354 354
355 355
356 ``->port_start()`` is called just after the da 356 ``->port_start()`` is called just after the data structures for each port
357 are initialized. Typically this is used to all 357 are initialized. Typically this is used to alloc per-port DMA buffers /
358 tables / rings, enable DMA engines, and simila 358 tables / rings, enable DMA engines, and similar tasks. Some drivers also
359 use this entry point as a chance to allocate d 359 use this entry point as a chance to allocate driver-private memory for
360 ``ap->private_data``. 360 ``ap->private_data``.
361 361
362 Many drivers use :c:func:`ata_port_start` as t 362 Many drivers use :c:func:`ata_port_start` as this hook or call it from their
363 own :c:func:`port_start` hooks. :c:func:`ata_p 363 own :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for
364 a legacy IDE PRD table and returns. 364 a legacy IDE PRD table and returns.
365 365
366 ``->port_stop()`` is called after ``->host_sto 366 ``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
367 release DMA/memory resources, now that they ar 367 release DMA/memory resources, now that they are no longer actively being
368 used. Many drivers also free driver-private da 368 used. Many drivers also free driver-private data from port at this time.
369 369
370 ``->host_stop()`` is called after all ``->port 370 ``->host_stop()`` is called after all ``->port_stop()`` calls have completed.
371 The hook must finalize hardware shutdown, rele 371 The hook must finalize hardware shutdown, release DMA and other
372 resources, etc. This hook may be specified as 372 resources, etc. This hook may be specified as NULL, in which case it is
373 not called. 373 not called.
374 374
375 Error handling 375 Error handling
376 ============== 376 ==============
377 377
378 This chapter describes how errors are handled 378 This chapter describes how errors are handled under libata. Readers are
379 advised to read SCSI EH (Documentation/scsi/sc 379 advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA
380 exceptions doc first. 380 exceptions doc first.
381 381
382 Origins of commands 382 Origins of commands
383 ------------------- 383 -------------------
384 384
385 In libata, a command is represented with 385 In libata, a command is represented with
386 :c:type:`struct ata_queued_cmd <ata_queued_cmd 386 :c:type:`struct ata_queued_cmd <ata_queued_cmd>` or qc.
387 qc's are preallocated during port initializati 387 qc's are preallocated during port initialization and repetitively used
388 for command executions. Currently only one qc 388 for command executions. Currently only one qc is allocated per port but
389 yet-to-be-merged NCQ branch allocates one for 389 yet-to-be-merged NCQ branch allocates one for each tag and maps each qc
390 to NCQ tag 1-to-1. 390 to NCQ tag 1-to-1.
391 391
392 libata commands can originate from two sources 392 libata commands can originate from two sources - libata itself and SCSI
393 midlayer. libata internal commands are used fo 393 midlayer. libata internal commands are used for initialization and error
394 handling. All normal blk requests and commands 394 handling. All normal blk requests and commands for SCSI emulation are
395 passed as SCSI commands through queuecommand c 395 passed as SCSI commands through queuecommand callback of SCSI host
396 template. 396 template.
397 397
398 How commands are issued 398 How commands are issued
399 ----------------------- 399 -----------------------
400 400
401 Internal commands 401 Internal commands
402 Once allocated qc's taskfile is initialize 402 Once allocated qc's taskfile is initialized for the command to be
403 executed. qc currently has two mechanisms 403 executed. qc currently has two mechanisms to notify completion. One
404 is via ``qc->complete_fn()`` callback and 404 is via ``qc->complete_fn()`` callback and the other is completion
405 ``qc->waiting``. ``qc->complete_fn()`` cal 405 ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path
406 used by normal SCSI translated commands an 406 used by normal SCSI translated commands and ``qc->waiting`` is the
407 synchronous (issuer sleeps in process cont 407 synchronous (issuer sleeps in process context) path used by internal
408 commands. 408 commands.
409 409
410 Once initialization is complete, host_set 410 Once initialization is complete, host_set lock is acquired and the
411 qc is issued. 411 qc is issued.
412 412
413 SCSI commands 413 SCSI commands
414 All libata drivers use :c:func:`ata_scsi_q 414 All libata drivers use :c:func:`ata_scsi_queuecmd` as
415 ``hostt->queuecommand`` callback. scmds ca 415 ``hostt->queuecommand`` callback. scmds can either be simulated or
416 translated. No qc is involved in processin 416 translated. No qc is involved in processing a simulated scmd. The
417 result is computed right away and the scmd 417 result is computed right away and the scmd is completed.
418 418
419 ``qc->complete_fn()`` callback is used for 419 ``qc->complete_fn()`` callback is used for completion notification. ATA
420 commands use :c:func:`ata_scsi_qc_complete 420 commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use
421 :c:func:`atapi_qc_complete`. Both function 421 :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
422 to notify upper layer when the qc is finis 422 to notify upper layer when the qc is finished. After translation is
423 completed, the qc is issued with :c:func:` 423 completed, the qc is issued with :c:func:`ata_qc_issue`.
424 424
425 Note that SCSI midlayer invokes hostt->que 425 Note that SCSI midlayer invokes hostt->queuecommand while holding
426 host_set lock, so all above occur while ho 426 host_set lock, so all above occur while holding host_set lock.
427 427
428 How commands are processed 428 How commands are processed
429 -------------------------- 429 --------------------------
430 430
431 Depending on which protocol and which controll 431 Depending on which protocol and which controller are used, commands are
432 processed differently. For the purpose of disc 432 processed differently. For the purpose of discussion, a controller which
433 uses taskfile interface and all standard callb 433 uses taskfile interface and all standard callbacks is assumed.
434 434
435 Currently 6 ATA command protocols are used. Th 435 Currently 6 ATA command protocols are used. They can be sorted into the
436 following four categories according to how the 436 following four categories according to how they are processed.
437 437
438 ATA NO DATA or DMA 438 ATA NO DATA or DMA
439 ATA_PROT_NODATA and ATA_PROT_DMA fall into 439 ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These
440 types of commands don't require any softwa 440 types of commands don't require any software intervention once
441 issued. Device will raise interrupt on com 441 issued. Device will raise interrupt on completion.
442 442
443 ATA PIO 443 ATA PIO
444 ATA_PROT_PIO is in this category. libata c 444 ATA_PROT_PIO is in this category. libata currently implements PIO
445 with polling. ATA_NIEN bit is set to turn 445 with polling. ATA_NIEN bit is set to turn off interrupt and
446 pio_task on ata_wq performs polling and IO 446 pio_task on ata_wq performs polling and IO.
447 447
448 ATAPI NODATA or DMA 448 ATAPI NODATA or DMA
449 ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_D 449 ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this
450 category. packet_task is used to poll BSY 450 category. packet_task is used to poll BSY bit after issuing PACKET
451 command. Once BSY is turned off by the dev 451 command. Once BSY is turned off by the device, packet_task
452 transfers CDB and hands off processing to 452 transfers CDB and hands off processing to interrupt handler.
453 453
454 ATAPI PIO 454 ATAPI PIO
455 ATA_PROT_ATAPI is in this category. ATA_NI 455 ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as
456 in ATAPI NODATA or DMA, packet_task submit 456 in ATAPI NODATA or DMA, packet_task submits cdb. However, after
457 submitting cdb, further processing (data t 457 submitting cdb, further processing (data transfer) is handed off to
458 pio_task. 458 pio_task.
459 459
460 How commands are completed 460 How commands are completed
461 -------------------------- 461 --------------------------
462 462
463 Once issued, all qc's are either completed wit 463 Once issued, all qc's are either completed with :c:func:`ata_qc_complete` or
464 time out. For commands which are handled by in 464 time out. For commands which are handled by interrupts,
465 :c:func:`ata_host_intr` invokes :c:func:`ata_q 465 :c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks,
466 pio_task invokes :c:func:`ata_qc_complete`. In 466 pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may
467 also complete commands. 467 also complete commands.
468 468
469 :c:func:`ata_qc_complete` does the following. 469 :c:func:`ata_qc_complete` does the following.
470 470
471 1. DMA memory is unmapped. 471 1. DMA memory is unmapped.
472 472
473 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags 473 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
474 474
475 3. :c:expr:`qc->complete_fn` callback is invok 475 3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
476 callback is not zero. Completion is short c 476 callback is not zero. Completion is short circuited and
477 :c:func:`ata_qc_complete` returns. 477 :c:func:`ata_qc_complete` returns.
478 478
479 4. :c:func:`__ata_qc_complete` is called, whic 479 4. :c:func:`__ata_qc_complete` is called, which does
480 480
481 1. ``qc->flags`` is cleared to zero. 481 1. ``qc->flags`` is cleared to zero.
482 482
483 2. ``ap->active_tag`` and ``qc->tag`` are p 483 2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
484 484
485 3. ``qc->waiting`` is cleared & completed ( 485 3. ``qc->waiting`` is cleared & completed (in that order).
486 486
487 4. qc is deallocated by clearing appropriat 487 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
488 488
489 So, it basically notifies upper layer and deal 489 So, it basically notifies upper layer and deallocates qc. One exception
490 is short-circuit path in #3 which is used by : 490 is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
491 491
492 For all non-ATAPI commands, whether it fails o 492 For all non-ATAPI commands, whether it fails or not, almost the same
493 code path is taken and very little error handl 493 code path is taken and very little error handling takes place. A qc is
494 completed with success status if it succeeded, 494 completed with success status if it succeeded, with failed status
495 otherwise. 495 otherwise.
496 496
497 However, failed ATAPI commands require more ha 497 However, failed ATAPI commands require more handling as REQUEST SENSE is
498 needed to acquire sense data. If an ATAPI comm 498 needed to acquire sense data. If an ATAPI command fails,
499 :c:func:`ata_qc_complete` is invoked with erro 499 :c:func:`ata_qc_complete` is invoked with error status, which in turn invokes
500 :c:func:`atapi_qc_complete` via ``qc->complete 500 :c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
501 501
502 This makes :c:func:`atapi_qc_complete` set ``s 502 This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
503 SAM_STAT_CHECK_CONDITION, complete the scmd an 503 SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the
504 sense data is empty but ``scmd->result`` is CH 504 sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
505 will invoke EH for the scmd, and returning 1 m 505 will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete`
506 to return without deallocating the qc. This le 506 to return without deallocating the qc. This leads us to
507 :c:func:`ata_scsi_error` with partially comple 507 :c:func:`ata_scsi_error` with partially completed qc.
508 508
509 :c:func:`ata_scsi_error` 509 :c:func:`ata_scsi_error`
510 ------------------------ 510 ------------------------
511 511
512 :c:func:`ata_scsi_error` is the current ``tran 512 :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
513 for libata. As discussed above, this will be e 513 for libata. As discussed above, this will be entered in two cases -
514 timeout and ATAPI error completion. This funct 514 timeout and ATAPI error completion. This function will check if a qc is active
515 and has not failed yet. Such a qc will be mark 515 and has not failed yet. Such a qc will be marked with AC_ERR_TIMEOUT such that
516 EH will know to handle it later. Then it calls 516 EH will know to handle it later. Then it calls low level libata driver's
517 :c:func:`error_handler` callback. 517 :c:func:`error_handler` callback.
518 518
519 When the :c:func:`error_handler` callback is i 519 When the :c:func:`error_handler` callback is invoked it stops BMDMA and
520 completes the qc. Note that as we're currently 520 completes the qc. Note that as we're currently in EH, we cannot call
521 scsi_done. As described in SCSI EH doc, a reco 521 scsi_done. As described in SCSI EH doc, a recovered scmd should be
522 either retried with :c:func:`scsi_queue_insert 522 either retried with :c:func:`scsi_queue_insert` or finished with
523 :c:func:`scsi_finish_command`. Here, we overri 523 :c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
524 :c:func:`scsi_finish_command` and calls :c:fun 524 :c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`.
525 525
526 If EH is invoked due to a failed ATAPI qc, the 526 If EH is invoked due to a failed ATAPI qc, the qc here is completed but
527 not deallocated. The purpose of this half-comp 527 not deallocated. The purpose of this half-completion is to use the qc as
528 place holder to make EH code reach this place. 528 place holder to make EH code reach this place. This is a bit hackish,
529 but it works. 529 but it works.
530 530
531 Once control reaches here, the qc is deallocat 531 Once control reaches here, the qc is deallocated by invoking
532 :c:func:`__ata_qc_complete` explicitly. Then, 532 :c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE
533 is issued. Once sense data is acquired, scmd i 533 is issued. Once sense data is acquired, scmd is finished by directly
534 invoking :c:func:`scsi_finish_command` on the 534 invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already
535 have completed and deallocated the qc which wa 535 have completed and deallocated the qc which was associated with the
536 scmd, we don't need to/cannot call :c:func:`at 536 scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again.
537 537
538 Problems with the current EH 538 Problems with the current EH
539 ---------------------------- 539 ----------------------------
540 540
541 - Error representation is too crude. Currentl 541 - Error representation is too crude. Currently any and all error
542 conditions are represented with ATA STATUS 542 conditions are represented with ATA STATUS and ERROR registers.
543 Errors which aren't ATA device errors are t 543 Errors which aren't ATA device errors are treated as ATA device
544 errors by setting ATA_ERR bit. Better error 544 errors by setting ATA_ERR bit. Better error descriptor which can
545 properly represent ATA and other errors/exc 545 properly represent ATA and other errors/exceptions is needed.
546 546
547 - When handling timeouts, no action is taken 547 - When handling timeouts, no action is taken to make device forget
548 about the timed out command and ready for n 548 about the timed out command and ready for new commands.
549 549
550 - EH handling via :c:func:`ata_scsi_error` is 550 - EH handling via :c:func:`ata_scsi_error` is not properly protected from
551 usual command processing. On EH entrance, t 551 usual command processing. On EH entrance, the device is not in
552 quiescent state. Timed out commands may suc 552 quiescent state. Timed out commands may succeed or fail any time.
553 pio_task and atapi_task may still be runnin 553 pio_task and atapi_task may still be running.
554 554
555 - Too weak error recovery. Devices / controll 555 - Too weak error recovery. Devices / controllers causing HSM mismatch
556 errors and other errors quite often require 556 errors and other errors quite often require reset to return to known
557 state. Also, advanced error handling is nec 557 state. Also, advanced error handling is necessary to support features
558 like NCQ and hotplug. 558 like NCQ and hotplug.
559 559
560 - ATA errors are directly handled in the inte 560 - ATA errors are directly handled in the interrupt handler and PIO
561 errors in pio_task. This is problematic for 561 errors in pio_task. This is problematic for advanced error handling
562 for the following reasons. 562 for the following reasons.
563 563
564 First, advanced error handling often requir 564 First, advanced error handling often requires context and internal qc
565 execution. 565 execution.
566 566
567 Second, even a simple failure (say, CRC err 567 Second, even a simple failure (say, CRC error) needs information
568 gathering and could trigger complex error h 568 gathering and could trigger complex error handling (say, resetting &
569 reconfiguring). Having multiple code paths 569 reconfiguring). Having multiple code paths to gather information,
570 enter EH and trigger actions makes life pai 570 enter EH and trigger actions makes life painful.
571 571
572 Third, scattered EH code makes implementing 572 Third, scattered EH code makes implementing low level drivers
573 difficult. Low level drivers override libat 573 difficult. Low level drivers override libata callbacks. If EH is
574 scattered over several places, each affecte 574 scattered over several places, each affected callbacks should perform
575 its part of error handling. This can be err 575 its part of error handling. This can be error prone and painful.
576 576
577 libata Library 577 libata Library
578 ============== 578 ==============
579 579
580 .. kernel-doc:: drivers/ata/libata-core.c 580 .. kernel-doc:: drivers/ata/libata-core.c
581 :export: 581 :export:
582 582
583 libata Core Internals 583 libata Core Internals
584 ===================== 584 =====================
585 585
586 .. kernel-doc:: drivers/ata/libata-core.c 586 .. kernel-doc:: drivers/ata/libata-core.c
587 :internal: 587 :internal:
588 588
589 .. kernel-doc:: drivers/ata/libata-eh.c 589 .. kernel-doc:: drivers/ata/libata-eh.c
590 590
591 libata SCSI translation/emulation 591 libata SCSI translation/emulation
592 ================================= 592 =================================
593 593
594 .. kernel-doc:: drivers/ata/libata-scsi.c 594 .. kernel-doc:: drivers/ata/libata-scsi.c
595 :export: 595 :export:
596 596
597 .. kernel-doc:: drivers/ata/libata-scsi.c 597 .. kernel-doc:: drivers/ata/libata-scsi.c
598 :internal: 598 :internal:
599 599
600 ATA errors and exceptions 600 ATA errors and exceptions
601 ========================= 601 =========================
602 602
603 This chapter tries to identify what error/exce 603 This chapter tries to identify what error/exception conditions exist for
604 ATA/ATAPI devices and describe how they should 604 ATA/ATAPI devices and describe how they should be handled in
605 implementation-neutral way. 605 implementation-neutral way.
606 606
607 The term 'error' is used to describe condition 607 The term 'error' is used to describe conditions where either an explicit
608 error condition is reported from device or a c 608 error condition is reported from device or a command has timed out.
609 609
610 The term 'exception' is either used to describ 610 The term 'exception' is either used to describe exceptional conditions
611 which are not errors (say, power or hotplug ev 611 which are not errors (say, power or hotplug events), or to describe both
612 errors and non-error exceptional conditions. W 612 errors and non-error exceptional conditions. Where explicit distinction
613 between error and exception is necessary, the 613 between error and exception is necessary, the term 'non-error exception'
614 is used. 614 is used.
615 615
616 Exception categories 616 Exception categories
617 -------------------- 617 --------------------
618 618
619 Exceptions are described primarily with respec 619 Exceptions are described primarily with respect to legacy taskfile + bus
620 master IDE interface. If a controller provides 620 master IDE interface. If a controller provides other better mechanism
621 for error reporting, mapping those into catego 621 for error reporting, mapping those into categories described below
622 shouldn't be difficult. 622 shouldn't be difficult.
623 623
624 In the following sections, two recovery action 624 In the following sections, two recovery actions - reset and
625 reconfiguring transport - are mentioned. These 625 reconfiguring transport - are mentioned. These are described further in
626 `EH recovery actions <#exrec>`__. 626 `EH recovery actions <#exrec>`__.
627 627
628 HSM violation 628 HSM violation
629 ~~~~~~~~~~~~~ 629 ~~~~~~~~~~~~~
630 630
631 This error is indicated when STATUS value does 631 This error is indicated when STATUS value doesn't match HSM requirement
632 during issuing or execution any ATA/ATAPI comm 632 during issuing or execution any ATA/ATAPI command.
633 633
634 - ATA_STATUS doesn't contain !BSY && DRDY && 634 - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to
635 issue a command. 635 issue a command.
636 636
637 - !BSY && !DRQ during PIO data transfer. 637 - !BSY && !DRQ during PIO data transfer.
638 638
639 - DRQ on command completion. 639 - DRQ on command completion.
640 640
641 - !BSY && ERR after CDB transfer starts but b 641 - !BSY && ERR after CDB transfer starts but before the last byte of CDB
642 is transferred. ATA/ATAPI standard states t 642 is transferred. ATA/ATAPI standard states that "The device shall not
643 terminate the PACKET command with an error 643 terminate the PACKET command with an error before the last byte of
644 the command packet has been written" in the 644 the command packet has been written" in the error outputs description
645 of PACKET command and the state diagram doe 645 of PACKET command and the state diagram doesn't include such
646 transitions. 646 transitions.
647 647
648 In these cases, HSM is violated and not much i 648 In these cases, HSM is violated and not much information regarding the
649 error can be acquired from STATUS or ERROR reg 649 error can be acquired from STATUS or ERROR register. IOW, this error can
650 be anything - driver bug, faulty device, contr 650 be anything - driver bug, faulty device, controller and/or cable.
651 651
652 As HSM is violated, reset is necessary to rest 652 As HSM is violated, reset is necessary to restore known state.
653 Reconfiguring transport for lower speed might 653 Reconfiguring transport for lower speed might be helpful too as
654 transmission errors sometimes cause this kind 654 transmission errors sometimes cause this kind of errors.
655 655
656 ATA/ATAPI device error (non-NCQ / non-CHECK CO 656 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
657 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 657 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
658 658
659 These are errors detected and reported by ATA/ 659 These are errors detected and reported by ATA/ATAPI devices indicating
660 device problems. For this type of errors, STAT 660 device problems. For this type of errors, STATUS and ERROR register
661 values are valid and describe error condition. 661 values are valid and describe error condition. Note that some of ATA bus
662 errors are detected by ATA/ATAPI devices and r 662 errors are detected by ATA/ATAPI devices and reported using the same
663 mechanism as device errors. Those cases are de 663 mechanism as device errors. Those cases are described later in this
664 section. 664 section.
665 665
666 For ATA commands, this type of errors are indi 666 For ATA commands, this type of errors are indicated by !BSY && ERR
667 during command execution and on completion. 667 during command execution and on completion.
668 668
669 For ATAPI commands, 669 For ATAPI commands,
670 670
671 - !BSY && ERR && ABRT right after issuing PAC 671 - !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET
672 command is not supported and falls in this 672 command is not supported and falls in this category.
673 673
674 - !BSY && ERR(==CHK) && !ABRT after the last 674 - !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred
675 indicates CHECK CONDITION and doesn't fall 675 indicates CHECK CONDITION and doesn't fall in this category.
676 676
677 - !BSY && ERR(==CHK) && ABRT after the last b 677 - !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred
678 \*probably\* indicates CHECK CONDITION and 678 \*probably\* indicates CHECK CONDITION and doesn't fall in this
679 category. 679 category.
680 680
681 Of errors detected as above, the following are 681 Of errors detected as above, the following are not ATA/ATAPI device
682 errors but ATA bus errors and should be handle 682 errors but ATA bus errors and should be handled according to
683 `ATA bus error <#excatATAbusErr>`__. 683 `ATA bus error <#excatATAbusErr>`__.
684 684
685 CRC error during data transfer 685 CRC error during data transfer
686 This is indicated by ICRC bit in the ERROR 686 This is indicated by ICRC bit in the ERROR register and means that
687 corruption occurred during data transfer. 687 corruption occurred during data transfer. Up to ATA/ATAPI-7, the
688 standard specifies that this bit is only a 688 standard specifies that this bit is only applicable to UDMA
689 transfers but ATA/ATAPI-8 draft revision 1 689 transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be
690 applicable to multiword DMA and PIO. 690 applicable to multiword DMA and PIO.
691 691
692 ABRT error during data transfer or on completi 692 ABRT error during data transfer or on completion
693 Up to ATA/ATAPI-7, the standard specifies 693 Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on
694 ICRC errors and on cases where a device is 694 ICRC errors and on cases where a device is not able to complete a
695 command. Combined with the fact that MWDMA 695 command. Combined with the fact that MWDMA and PIO transfer errors
696 aren't allowed to use ICRC bit up to ATA/A 696 aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply
697 that ABRT bit alone could indicate transfe 697 that ABRT bit alone could indicate transfer errors.
698 698
699 However, ATA/ATAPI-8 draft revision 1f rem 699 However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC
700 errors can turn on ABRT. So, this is kind 700 errors can turn on ABRT. So, this is kind of gray area. Some
701 heuristics are needed here. 701 heuristics are needed here.
702 702
703 ATA/ATAPI device errors can be further categor 703 ATA/ATAPI device errors can be further categorized as follows.
704 704
705 Media errors 705 Media errors
706 This is indicated by UNC bit in the ERROR 706 This is indicated by UNC bit in the ERROR register. ATA devices
707 reports UNC error only after certain numbe 707 reports UNC error only after certain number of retries cannot
708 recover the data, so there's nothing much 708 recover the data, so there's nothing much else to do other than
709 notifying upper layer. 709 notifying upper layer.
710 710
711 READ and WRITE commands report CHS or LBA 711 READ and WRITE commands report CHS or LBA of the first failed sector
712 but ATA/ATAPI standard specifies that the 712 but ATA/ATAPI standard specifies that the amount of transferred data
713 on error completion is indeterminate, so w 713 on error completion is indeterminate, so we cannot assume that
714 sectors preceding the failed sector have b 714 sectors preceding the failed sector have been transferred and thus
715 cannot complete those sectors successfully 715 cannot complete those sectors successfully as SCSI does.
716 716
717 Media changed / media change requested error 717 Media changed / media change requested error
718 <<TODO: fill here>> 718 <<TODO: fill here>>
719 719
720 Address error 720 Address error
721 This is indicated by IDNF bit in the ERROR 721 This is indicated by IDNF bit in the ERROR register. Report to upper
722 layer. 722 layer.
723 723
724 Other errors 724 Other errors
725 This can be invalid command or parameter i 725 This can be invalid command or parameter indicated by ABRT ERROR bit
726 or some other error condition. Note that A 726 or some other error condition. Note that ABRT bit can indicate a lot
727 of things including ICRC and Address error 727 of things including ICRC and Address errors. Heuristics needed.
728 728
729 Depending on commands, not all STATUS/ERROR bi 729 Depending on commands, not all STATUS/ERROR bits are applicable. These
730 non-applicable bits are marked with "na" in th 730 non-applicable bits are marked with "na" in the output descriptions but
731 up to ATA/ATAPI-7 no definition of "na" can be 731 up to ATA/ATAPI-7 no definition of "na" can be found. However,
732 ATA/ATAPI-8 draft revision 1f describes "N/A" 732 ATA/ATAPI-8 draft revision 1f describes "N/A" as follows.
733 733
734 3.2.3.3a N/A 734 3.2.3.3a N/A
735 A keyword the indicates a field has no 735 A keyword the indicates a field has no defined value in this
736 standard and should not be checked by 736 standard and should not be checked by the host or device. N/A
737 fields should be cleared to zero. 737 fields should be cleared to zero.
738 738
739 So, it seems reasonable to assume that "na" bi 739 So, it seems reasonable to assume that "na" bits are cleared to zero by
740 devices and thus need no explicit masking. 740 devices and thus need no explicit masking.
741 741
742 ATAPI device CHECK CONDITION 742 ATAPI device CHECK CONDITION
743 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 743 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
744 744
745 ATAPI device CHECK CONDITION error is indicate 745 ATAPI device CHECK CONDITION error is indicated by set CHK bit (ERR bit)
746 in the STATUS register after the last byte of 746 in the STATUS register after the last byte of CDB is transferred for a
747 PACKET command. For this kind of errors, sense 747 PACKET command. For this kind of errors, sense data should be acquired
748 to gather information regarding the errors. RE 748 to gather information regarding the errors. REQUEST SENSE packet command
749 should be used to acquire sense data. 749 should be used to acquire sense data.
750 750
751 Once sense data is acquired, this type of erro 751 Once sense data is acquired, this type of errors can be handled
752 similarly to other SCSI errors. Note that sens 752 similarly to other SCSI errors. Note that sense data may indicate ATA
753 bus error (e.g. Sense Key 04h HARDWARE ERROR & 753 bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI
754 PARITY ERROR). In such cases, the error should 754 PARITY ERROR). In such cases, the error should be considered as an ATA
755 bus error and handled according to `ATA bus er 755 bus error and handled according to `ATA bus error <#excatATAbusErr>`__.
756 756
757 ATA device error (NCQ) 757 ATA device error (NCQ)
758 ~~~~~~~~~~~~~~~~~~~~~~ 758 ~~~~~~~~~~~~~~~~~~~~~~
759 759
760 NCQ command error is indicated by cleared BSY 760 NCQ command error is indicated by cleared BSY and set ERR bit during NCQ
761 command phase (one or more NCQ commands outsta 761 command phase (one or more NCQ commands outstanding). Although STATUS
762 and ERROR registers will contain valid values 762 and ERROR registers will contain valid values describing the error, READ
763 LOG EXT is required to clear the error conditi 763 LOG EXT is required to clear the error condition, determine which
764 command has failed and acquire more informatio 764 command has failed and acquire more information.
765 765
766 READ LOG EXT Log Page 10h reports which tag ha 766 READ LOG EXT Log Page 10h reports which tag has failed and taskfile
767 register values describing the error. With thi 767 register values describing the error. With this information the failed
768 command can be handled as a normal ATA command 768 command can be handled as a normal ATA command error as in
769 `ATA/ATAPI device error (non-NCQ / non-CHECK C 769 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__
770 and all other in-flight commands must be retri 770 and all other in-flight commands must be retried. Note that this retry
771 should not be counted - it's likely that comma 771 should not be counted - it's likely that commands retried this way would
772 have completed normally if it were not for the 772 have completed normally if it were not for the failed command.
773 773
774 Note that ATA bus errors can be reported as AT 774 Note that ATA bus errors can be reported as ATA device NCQ errors. This
775 should be handled as described in `ATA bus err 775 should be handled as described in `ATA bus error <#excatATAbusErr>`__.
776 776
777 If READ LOG EXT Log Page 10h fails or reports 777 If READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly
778 screwed. This condition should be treated acco 778 screwed. This condition should be treated according to
779 `HSM violation <#excatHSMviolation>`__. 779 `HSM violation <#excatHSMviolation>`__.
780 780
781 ATA bus error 781 ATA bus error
782 ~~~~~~~~~~~~~ 782 ~~~~~~~~~~~~~
783 783
784 ATA bus error means that data corruption occur 784 ATA bus error means that data corruption occurred during transmission
785 over ATA bus (SATA or PATA). This type of erro 785 over ATA bus (SATA or PATA). This type of errors can be indicated by
786 786
787 - ICRC or ABRT error as described in 787 - ICRC or ABRT error as described in
788 `ATA/ATAPI device error (non-NCQ / non-CHEC 788 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__.
789 789
790 - Controller-specific error completion with e 790 - Controller-specific error completion with error information
791 indicating transmission error. 791 indicating transmission error.
792 792
793 - On some controllers, command timeout. In th 793 - On some controllers, command timeout. In this case, there may be a
794 mechanism to determine that the timeout is 794 mechanism to determine that the timeout is due to transmission error.
795 795
796 - Unknown/random errors, timeouts and all sor 796 - Unknown/random errors, timeouts and all sorts of weirdities.
797 797
798 As described above, transmission errors can ca 798 As described above, transmission errors can cause wide variety of
799 symptoms ranging from device ICRC error to ran 799 symptoms ranging from device ICRC error to random device lockup, and,
800 for many cases, there is no way to tell if an 800 for many cases, there is no way to tell if an error condition is due to
801 transmission error or not; therefore, it's nec 801 transmission error or not; therefore, it's necessary to employ some kind
802 of heuristic when dealing with errors and time 802 of heuristic when dealing with errors and timeouts. For example,
803 encountering repetitive ABRT errors for known 803 encountering repetitive ABRT errors for known supported command is
804 likely to indicate ATA bus error. 804 likely to indicate ATA bus error.
805 805
806 Once it's determined that ATA bus errors have 806 Once it's determined that ATA bus errors have possibly occurred,
807 lowering ATA bus transmission speed is one of 807 lowering ATA bus transmission speed is one of actions which may
808 alleviate the problem. See `Reconfigure transp 808 alleviate the problem. See `Reconfigure transport <#exrecReconf>`__ for
809 more information. 809 more information.
810 810
811 PCI bus error 811 PCI bus error
812 ~~~~~~~~~~~~~ 812 ~~~~~~~~~~~~~
813 813
814 Data corruption or other failures during trans 814 Data corruption or other failures during transmission over PCI (or other
815 system bus). For standard BMDMA, this is indic 815 system bus). For standard BMDMA, this is indicated by Error bit in the
816 BMDMA Status register. This type of errors mus 816 BMDMA Status register. This type of errors must be logged as it
817 indicates something is very wrong with the sys 817 indicates something is very wrong with the system. Resetting host
818 controller is recommended. 818 controller is recommended.
819 819
820 Late completion 820 Late completion
821 ~~~~~~~~~~~~~~~ 821 ~~~~~~~~~~~~~~~
822 822
823 This occurs when timeout occurs and the timeou 823 This occurs when timeout occurs and the timeout handler finds out that
824 the timed out command has completed successful 824 the timed out command has completed successfully or with error. This is
825 usually caused by lost interrupts. This type o 825 usually caused by lost interrupts. This type of errors must be logged.
826 Resetting host controller is recommended. 826 Resetting host controller is recommended.
827 827
828 Unknown error (timeout) 828 Unknown error (timeout)
829 ~~~~~~~~~~~~~~~~~~~~~~~ 829 ~~~~~~~~~~~~~~~~~~~~~~~
830 830
831 This is when timeout occurs and the command is 831 This is when timeout occurs and the command is still processing or the
832 host and device are in unknown state. When thi 832 host and device are in unknown state. When this occurs, HSM could be in
833 any valid or invalid state. To bring the devic 833 any valid or invalid state. To bring the device to known state and make
834 it forget about the timed out command, resetti 834 it forget about the timed out command, resetting is necessary. The timed
835 out command may be retried. 835 out command may be retried.
836 836
837 Timeouts can also be caused by transmission er 837 Timeouts can also be caused by transmission errors. Refer to
838 `ATA bus error <#excatATAbusErr>`__ for more d 838 `ATA bus error <#excatATAbusErr>`__ for more details.
839 839
840 Hotplug and power management exceptions 840 Hotplug and power management exceptions
841 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 841 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
842 842
843 <<TODO: fill here>> 843 <<TODO: fill here>>
844 844
845 EH recovery actions 845 EH recovery actions
846 ------------------- 846 -------------------
847 847
848 This section discusses several important recov 848 This section discusses several important recovery actions.
849 849
850 Clearing error condition 850 Clearing error condition
851 ~~~~~~~~~~~~~~~~~~~~~~~~ 851 ~~~~~~~~~~~~~~~~~~~~~~~~
852 852
853 Many controllers require its error registers t 853 Many controllers require its error registers to be cleared by error
854 handler. Different controllers may have differ 854 handler. Different controllers may have different requirements.
855 855
856 For SATA, it's strongly recommended to clear a 856 For SATA, it's strongly recommended to clear at least SError register
857 during error handling. 857 during error handling.
858 858
859 Reset 859 Reset
860 ~~~~~ 860 ~~~~~
861 861
862 During EH, resetting is necessary in the follo 862 During EH, resetting is necessary in the following cases.
863 863
864 - HSM is in unknown or invalid state 864 - HSM is in unknown or invalid state
865 865
866 - HBA is in unknown or invalid state 866 - HBA is in unknown or invalid state
867 867
868 - EH needs to make HBA/device forget about in 868 - EH needs to make HBA/device forget about in-flight commands
869 869
870 - HBA/device behaves weirdly 870 - HBA/device behaves weirdly
871 871
872 Resetting during EH might be a good idea regar 872 Resetting during EH might be a good idea regardless of error condition
873 to improve EH robustness. Whether to reset bot 873 to improve EH robustness. Whether to reset both or either one of HBA and
874 device depends on situation but the following 874 device depends on situation but the following scheme is recommended.
875 875
876 - When it's known that HBA is in ready state 876 - When it's known that HBA is in ready state but ATA/ATAPI device is in
877 unknown state, reset only device. 877 unknown state, reset only device.
878 878
879 - If HBA is in unknown state, reset both HBA 879 - If HBA is in unknown state, reset both HBA and device.
880 880
881 HBA resetting is implementation specific. For 881 HBA resetting is implementation specific. For a controller complying to
882 taskfile/BMDMA PCI IDE, stopping active DMA tr 882 taskfile/BMDMA PCI IDE, stopping active DMA transaction may be
883 sufficient iff BMDMA state is the only HBA con 883 sufficient iff BMDMA state is the only HBA context. But even mostly
884 taskfile/BMDMA PCI IDE complying controllers m 884 taskfile/BMDMA PCI IDE complying controllers may have implementation
885 specific requirements and mechanism to reset t 885 specific requirements and mechanism to reset themselves. This must be
886 addressed by specific drivers. 886 addressed by specific drivers.
887 887
888 OTOH, ATA/ATAPI standard describes in detail w 888 OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI
889 devices. 889 devices.
890 890
891 PATA hardware reset 891 PATA hardware reset
892 This is hardware initiated device reset si 892 This is hardware initiated device reset signalled with asserted PATA
893 RESET- signal. There is no standard way to 893 RESET- signal. There is no standard way to initiate hardware reset
894 from software although some hardware provi 894 from software although some hardware provides registers that allow
895 driver to directly tweak the RESET- signal 895 driver to directly tweak the RESET- signal.
896 896
897 Software reset 897 Software reset
898 This is achieved by turning CONTROL SRST b 898 This is achieved by turning CONTROL SRST bit on for at least 5us.
899 Both PATA and SATA support it but, in case 899 Both PATA and SATA support it but, in case of SATA, this may require
900 controller-specific support as the second 900 controller-specific support as the second Register FIS to clear SRST
901 should be transmitted while BSY bit is sti 901 should be transmitted while BSY bit is still set. Note that on PATA,
902 this resets both master and slave devices 902 this resets both master and slave devices on a channel.
903 903
904 EXECUTE DEVICE DIAGNOSTIC command 904 EXECUTE DEVICE DIAGNOSTIC command
905 Although ATA/ATAPI standard doesn't descri 905 Although ATA/ATAPI standard doesn't describe exactly, EDD implies
906 some level of resetting, possibly similar 906 some level of resetting, possibly similar level with software reset.
907 Host-side EDD protocol can be handled with 907 Host-side EDD protocol can be handled with normal command processing
908 and most SATA controllers should be able t 908 and most SATA controllers should be able to handle EDD's just like
909 other commands. As in software reset, EDD 909 other commands. As in software reset, EDD affects both devices on a
910 PATA bus. 910 PATA bus.
911 911
912 Although EDD does reset devices, this does 912 Although EDD does reset devices, this doesn't suit error handling as
913 EDD cannot be issued while BSY is set and 913 EDD cannot be issued while BSY is set and it's unclear how it will
914 act when device is in unknown/weird state. 914 act when device is in unknown/weird state.
915 915
916 ATAPI DEVICE RESET command 916 ATAPI DEVICE RESET command
917 This is very similar to software reset exc 917 This is very similar to software reset except that reset can be
918 restricted to the selected device without 918 restricted to the selected device without affecting the other device
919 sharing the cable. 919 sharing the cable.
920 920
921 SATA phy reset 921 SATA phy reset
922 This is the preferred way of resetting a S 922 This is the preferred way of resetting a SATA device. In effect,
923 it's identical to PATA hardware reset. Not 923 it's identical to PATA hardware reset. Note that this can be done
924 with the standard SCR Control register. As 924 with the standard SCR Control register. As such, it's usually easier
925 to implement than software reset. 925 to implement than software reset.
926 926
927 One more thing to consider when resetting devi 927 One more thing to consider when resetting devices is that resetting
928 clears certain configuration parameters and th 928 clears certain configuration parameters and they need to be set to their
929 previous or newly adjusted values after reset. 929 previous or newly adjusted values after reset.
930 930
931 Parameters affected are. 931 Parameters affected are.
932 932
933 - CHS set up with INITIALIZE DEVICE PARAMETER 933 - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
934 934
935 - Parameters set with SET FEATURES including 935 - Parameters set with SET FEATURES including transfer mode setting
936 936
937 - Block count set with SET MULTIPLE MODE 937 - Block count set with SET MULTIPLE MODE
938 938
939 - Other parameters (SET MAX, MEDIA LOCK...) 939 - Other parameters (SET MAX, MEDIA LOCK...)
940 940
941 ATA/ATAPI standard specifies that some paramet 941 ATA/ATAPI standard specifies that some parameters must be maintained
942 across hardware or software reset, but doesn't 942 across hardware or software reset, but doesn't strictly specify all of
943 them. Always reconfiguring needed parameters a 943 them. Always reconfiguring needed parameters after reset is required for
944 robustness. Note that this also applies when r 944 robustness. Note that this also applies when resuming from deep sleep
945 (power-off). 945 (power-off).
946 946
947 Also, ATA/ATAPI standard requires that IDENTIF 947 Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET
948 DEVICE is issued after any configuration param 948 DEVICE is issued after any configuration parameter is updated or a
949 hardware reset and the result used for further 949 hardware reset and the result used for further operation. OS driver is
950 required to implement revalidation mechanism t 950 required to implement revalidation mechanism to support this.
951 951
952 Reconfigure transport 952 Reconfigure transport
953 ~~~~~~~~~~~~~~~~~~~~~ 953 ~~~~~~~~~~~~~~~~~~~~~
954 954
955 For both PATA and SATA, a lot of corners are c 955 For both PATA and SATA, a lot of corners are cut for cheap connectors,
956 cables or controllers and it's quite common to 956 cables or controllers and it's quite common to see high transmission
957 error rate. This can be mitigated by lowering 957 error rate. This can be mitigated by lowering transmission speed.
958 958
959 The following is a possible scheme Jeff Garzik 959 The following is a possible scheme Jeff Garzik suggested.
960 960
961 If more than $N (3?) transmission errors h 961 If more than $N (3?) transmission errors happen in 15 minutes,
962 962
963 - if SATA, decrease SATA PHY speed. if sp 963 - if SATA, decrease SATA PHY speed. if speed cannot be decreased,
964 964
965 - decrease UDMA xfer speed. if at UDMA0, 965 - decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
966 966
967 - decrease PIO xfer speed. if at PIO3, co 967 - decrease PIO xfer speed. if at PIO3, complain, but continue
968 968
969 ata_piix Internals 969 ata_piix Internals
970 =================== 970 ===================
971 971
972 .. kernel-doc:: drivers/ata/ata_piix.c 972 .. kernel-doc:: drivers/ata/ata_piix.c
973 :internal: 973 :internal:
974 974
975 sata_sil Internals 975 sata_sil Internals
976 =================== 976 ===================
977 977
978 .. kernel-doc:: drivers/ata/sata_sil.c 978 .. kernel-doc:: drivers/ata/sata_sil.c
979 :internal: 979 :internal:
980 980
981 Thanks 981 Thanks
982 ====== 982 ======
983 983
984 The bulk of the ATA knowledge comes thanks to 984 The bulk of the ATA knowledge comes thanks to long conversations with
985 Andre Hedrick (www.linux-ide.org), and long ho 985 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and
986 SCSI specifications. 986 SCSI specifications.
987 987
988 Thanks to Alan Cox for pointing out similariti 988 Thanks to Alan Cox for pointing out similarities between SATA and SCSI,
989 and in general for motivation to hack on libat 989 and in general for motivation to hack on libata.
990 990
991 libata's device detection method, ata_pio_devc 991 libata's device detection method, ata_pio_devchk, and in general all
992 the early probing was based on extensive study 992 the early probing was based on extensive study of Hale Landis's
993 probe/reset code in his ATADRVR driver (www.at 993 probe/reset code in his ATADRVR driver (www.ata-atapi.com).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.