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