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