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
402 Once allocated qc's taskfile is initialize 427 Once allocated qc's taskfile is initialized for the command to be
403 executed. qc currently has two mechanisms 428 executed. qc currently has two mechanisms to notify completion. One
404 is via ``qc->complete_fn()`` callback and 429 is via ``qc->complete_fn()`` callback and the other is completion
405 ``qc->waiting``. ``qc->complete_fn()`` cal 430 ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path
406 used by normal SCSI translated commands an 431 used by normal SCSI translated commands and ``qc->waiting`` is the
407 synchronous (issuer sleeps in process cont 432 synchronous (issuer sleeps in process context) path used by internal
408 commands. 433 commands.
409 434
410 Once initialization is complete, host_set 435 Once initialization is complete, host_set lock is acquired and the
411 qc is issued. 436 qc is issued.
412 437
413 SCSI commands 438 SCSI commands
414 All libata drivers use :c:func:`ata_scsi_q 439 All libata drivers use :c:func:`ata_scsi_queuecmd` as
415 ``hostt->queuecommand`` callback. scmds ca 440 ``hostt->queuecommand`` callback. scmds can either be simulated or
416 translated. No qc is involved in processin 441 translated. No qc is involved in processing a simulated scmd. The
417 result is computed right away and the scmd 442 result is computed right away and the scmd is completed.
418 443
419 ``qc->complete_fn()`` callback is used for 444 ``qc->complete_fn()`` callback is used for completion notification. ATA
420 commands use :c:func:`ata_scsi_qc_complete 445 commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use
421 :c:func:`atapi_qc_complete`. Both function 446 :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
422 to notify upper layer when the qc is finis 447 to notify upper layer when the qc is finished. After translation is
423 completed, the qc is issued with :c:func:` 448 completed, the qc is issued with :c:func:`ata_qc_issue`.
424 449
425 Note that SCSI midlayer invokes hostt->que 450 Note that SCSI midlayer invokes hostt->queuecommand while holding
426 host_set lock, so all above occur while ho 451 host_set lock, so all above occur while holding host_set lock.
427 452
428 How commands are processed 453 How commands are processed
429 -------------------------- 454 --------------------------
430 455
431 Depending on which protocol and which controll 456 Depending on which protocol and which controller are used, commands are
432 processed differently. For the purpose of disc 457 processed differently. For the purpose of discussion, a controller which
433 uses taskfile interface and all standard callb 458 uses taskfile interface and all standard callbacks is assumed.
434 459
435 Currently 6 ATA command protocols are used. Th 460 Currently 6 ATA command protocols are used. They can be sorted into the
436 following four categories according to how the 461 following four categories according to how they are processed.
437 462
438 ATA NO DATA or DMA 463 ATA NO DATA or DMA
439 ATA_PROT_NODATA and ATA_PROT_DMA fall into 464 ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These
440 types of commands don't require any softwa 465 types of commands don't require any software intervention once
441 issued. Device will raise interrupt on com 466 issued. Device will raise interrupt on completion.
442 467
443 ATA PIO 468 ATA PIO
444 ATA_PROT_PIO is in this category. libata c 469 ATA_PROT_PIO is in this category. libata currently implements PIO
445 with polling. ATA_NIEN bit is set to turn 470 with polling. ATA_NIEN bit is set to turn off interrupt and
446 pio_task on ata_wq performs polling and IO 471 pio_task on ata_wq performs polling and IO.
447 472
448 ATAPI NODATA or DMA 473 ATAPI NODATA or DMA
449 ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_D 474 ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this
450 category. packet_task is used to poll BSY 475 category. packet_task is used to poll BSY bit after issuing PACKET
451 command. Once BSY is turned off by the dev 476 command. Once BSY is turned off by the device, packet_task
452 transfers CDB and hands off processing to 477 transfers CDB and hands off processing to interrupt handler.
453 478
454 ATAPI PIO 479 ATAPI PIO
455 ATA_PROT_ATAPI is in this category. ATA_NI 480 ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as
456 in ATAPI NODATA or DMA, packet_task submit 481 in ATAPI NODATA or DMA, packet_task submits cdb. However, after
457 submitting cdb, further processing (data t 482 submitting cdb, further processing (data transfer) is handed off to
458 pio_task. 483 pio_task.
459 484
460 How commands are completed 485 How commands are completed
461 -------------------------- 486 --------------------------
462 487
463 Once issued, all qc's are either completed wit 488 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 489 time out. For commands which are handled by interrupts,
465 :c:func:`ata_host_intr` invokes :c:func:`ata_q 490 :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 491 pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may
467 also complete commands. 492 also complete commands.
468 493
469 :c:func:`ata_qc_complete` does the following. 494 :c:func:`ata_qc_complete` does the following.
470 495
471 1. DMA memory is unmapped. 496 1. DMA memory is unmapped.
472 497
473 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags 498 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
474 499
475 3. :c:expr:`qc->complete_fn` callback is invok 500 3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
476 callback is not zero. Completion is short c 501 callback is not zero. Completion is short circuited and
477 :c:func:`ata_qc_complete` returns. 502 :c:func:`ata_qc_complete` returns.
478 503
479 4. :c:func:`__ata_qc_complete` is called, whic 504 4. :c:func:`__ata_qc_complete` is called, which does
480 505
481 1. ``qc->flags`` is cleared to zero. 506 1. ``qc->flags`` is cleared to zero.
482 507
483 2. ``ap->active_tag`` and ``qc->tag`` are p 508 2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
484 509
485 3. ``qc->waiting`` is cleared & completed ( 510 3. ``qc->waiting`` is cleared & completed (in that order).
486 511
487 4. qc is deallocated by clearing appropriat 512 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
488 513
489 So, it basically notifies upper layer and deal 514 So, it basically notifies upper layer and deallocates qc. One exception
490 is short-circuit path in #3 which is used by : 515 is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
491 516
492 For all non-ATAPI commands, whether it fails o 517 For all non-ATAPI commands, whether it fails or not, almost the same
493 code path is taken and very little error handl 518 code path is taken and very little error handling takes place. A qc is
494 completed with success status if it succeeded, 519 completed with success status if it succeeded, with failed status
495 otherwise. 520 otherwise.
496 521
497 However, failed ATAPI commands require more ha 522 However, failed ATAPI commands require more handling as REQUEST SENSE is
498 needed to acquire sense data. If an ATAPI comm 523 needed to acquire sense data. If an ATAPI command fails,
499 :c:func:`ata_qc_complete` is invoked with erro 524 :c:func:`ata_qc_complete` is invoked with error status, which in turn invokes
500 :c:func:`atapi_qc_complete` via ``qc->complete 525 :c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
501 526
502 This makes :c:func:`atapi_qc_complete` set ``s 527 This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
503 SAM_STAT_CHECK_CONDITION, complete the scmd an 528 SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the
504 sense data is empty but ``scmd->result`` is CH 529 sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
505 will invoke EH for the scmd, and returning 1 m 530 will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete`
506 to return without deallocating the qc. This le 531 to return without deallocating the qc. This leads us to
507 :c:func:`ata_scsi_error` with partially comple 532 :c:func:`ata_scsi_error` with partially completed qc.
508 533
509 :c:func:`ata_scsi_error` 534 :c:func:`ata_scsi_error`
510 ------------------------ 535 ------------------------
511 536
512 :c:func:`ata_scsi_error` is the current ``tran 537 :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
513 for libata. As discussed above, this will be e 538 for libata. As discussed above, this will be entered in two cases -
514 timeout and ATAPI error completion. This funct !! 539 timeout and ATAPI error completion. This function calls low level libata
515 and has not failed yet. Such a qc will be mark !! 540 driver's :c:func:`eng_timeout` callback, the standard callback for which is
516 EH will know to handle it later. Then it calls !! 541 :c:func:`ata_eng_timeout`. It checks if a qc is active and calls
517 :c:func:`error_handler` callback. !! 542 :c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in
>> 543 :c:func:`ata_qc_timeout`.
518 544
519 When the :c:func:`error_handler` callback is i !! 545 If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and
520 completes the qc. Note that as we're currently 546 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 547 scsi_done. As described in SCSI EH doc, a recovered scmd should be
522 either retried with :c:func:`scsi_queue_insert 548 either retried with :c:func:`scsi_queue_insert` or finished with
523 :c:func:`scsi_finish_command`. Here, we overri 549 :c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
524 :c:func:`scsi_finish_command` and calls :c:fun 550 :c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`.
525 551
526 If EH is invoked due to a failed ATAPI qc, the 552 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 553 not deallocated. The purpose of this half-completion is to use the qc as
528 place holder to make EH code reach this place. 554 place holder to make EH code reach this place. This is a bit hackish,
529 but it works. 555 but it works.
530 556
531 Once control reaches here, the qc is deallocat 557 Once control reaches here, the qc is deallocated by invoking
532 :c:func:`__ata_qc_complete` explicitly. Then, 558 :c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE
533 is issued. Once sense data is acquired, scmd i 559 is issued. Once sense data is acquired, scmd is finished by directly
534 invoking :c:func:`scsi_finish_command` on the 560 invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already
535 have completed and deallocated the qc which wa 561 have completed and deallocated the qc which was associated with the
536 scmd, we don't need to/cannot call :c:func:`at 562 scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again.
537 563
538 Problems with the current EH 564 Problems with the current EH
539 ---------------------------- 565 ----------------------------
540 566
541 - Error representation is too crude. Currentl 567 - Error representation is too crude. Currently any and all error
542 conditions are represented with ATA STATUS 568 conditions are represented with ATA STATUS and ERROR registers.
543 Errors which aren't ATA device errors are t 569 Errors which aren't ATA device errors are treated as ATA device
544 errors by setting ATA_ERR bit. Better error 570 errors by setting ATA_ERR bit. Better error descriptor which can
545 properly represent ATA and other errors/exc 571 properly represent ATA and other errors/exceptions is needed.
546 572
547 - When handling timeouts, no action is taken 573 - When handling timeouts, no action is taken to make device forget
548 about the timed out command and ready for n 574 about the timed out command and ready for new commands.
549 575
550 - EH handling via :c:func:`ata_scsi_error` is 576 - EH handling via :c:func:`ata_scsi_error` is not properly protected from
551 usual command processing. On EH entrance, t 577 usual command processing. On EH entrance, the device is not in
552 quiescent state. Timed out commands may suc 578 quiescent state. Timed out commands may succeed or fail any time.
553 pio_task and atapi_task may still be runnin 579 pio_task and atapi_task may still be running.
554 580
555 - Too weak error recovery. Devices / controll 581 - Too weak error recovery. Devices / controllers causing HSM mismatch
556 errors and other errors quite often require 582 errors and other errors quite often require reset to return to known
557 state. Also, advanced error handling is nec 583 state. Also, advanced error handling is necessary to support features
558 like NCQ and hotplug. 584 like NCQ and hotplug.
559 585
560 - ATA errors are directly handled in the inte 586 - ATA errors are directly handled in the interrupt handler and PIO
561 errors in pio_task. This is problematic for 587 errors in pio_task. This is problematic for advanced error handling
562 for the following reasons. 588 for the following reasons.
563 589
564 First, advanced error handling often requir 590 First, advanced error handling often requires context and internal qc
565 execution. 591 execution.
566 592
567 Second, even a simple failure (say, CRC err 593 Second, even a simple failure (say, CRC error) needs information
568 gathering and could trigger complex error h 594 gathering and could trigger complex error handling (say, resetting &
569 reconfiguring). Having multiple code paths 595 reconfiguring). Having multiple code paths to gather information,
570 enter EH and trigger actions makes life pai 596 enter EH and trigger actions makes life painful.
571 597
572 Third, scattered EH code makes implementing 598 Third, scattered EH code makes implementing low level drivers
573 difficult. Low level drivers override libat 599 difficult. Low level drivers override libata callbacks. If EH is
574 scattered over several places, each affecte 600 scattered over several places, each affected callbacks should perform
575 its part of error handling. This can be err 601 its part of error handling. This can be error prone and painful.
576 602
577 libata Library 603 libata Library
578 ============== 604 ==============
579 605
580 .. kernel-doc:: drivers/ata/libata-core.c 606 .. kernel-doc:: drivers/ata/libata-core.c
581 :export: 607 :export:
582 608
583 libata Core Internals 609 libata Core Internals
584 ===================== 610 =====================
585 611
586 .. kernel-doc:: drivers/ata/libata-core.c 612 .. kernel-doc:: drivers/ata/libata-core.c
587 :internal: 613 :internal:
588 614
589 .. kernel-doc:: drivers/ata/libata-eh.c 615 .. kernel-doc:: drivers/ata/libata-eh.c
590 616
591 libata SCSI translation/emulation 617 libata SCSI translation/emulation
592 ================================= 618 =================================
593 619
594 .. kernel-doc:: drivers/ata/libata-scsi.c 620 .. kernel-doc:: drivers/ata/libata-scsi.c
595 :export: 621 :export:
596 622
597 .. kernel-doc:: drivers/ata/libata-scsi.c 623 .. kernel-doc:: drivers/ata/libata-scsi.c
598 :internal: 624 :internal:
599 625
600 ATA errors and exceptions 626 ATA errors and exceptions
601 ========================= 627 =========================
602 628
603 This chapter tries to identify what error/exce 629 This chapter tries to identify what error/exception conditions exist for
604 ATA/ATAPI devices and describe how they should 630 ATA/ATAPI devices and describe how they should be handled in
605 implementation-neutral way. 631 implementation-neutral way.
606 632
607 The term 'error' is used to describe condition 633 The term 'error' is used to describe conditions where either an explicit
608 error condition is reported from device or a c 634 error condition is reported from device or a command has timed out.
609 635
610 The term 'exception' is either used to describ 636 The term 'exception' is either used to describe exceptional conditions
611 which are not errors (say, power or hotplug ev 637 which are not errors (say, power or hotplug events), or to describe both
612 errors and non-error exceptional conditions. W 638 errors and non-error exceptional conditions. Where explicit distinction
613 between error and exception is necessary, the 639 between error and exception is necessary, the term 'non-error exception'
614 is used. 640 is used.
615 641
616 Exception categories 642 Exception categories
617 -------------------- 643 --------------------
618 644
619 Exceptions are described primarily with respec 645 Exceptions are described primarily with respect to legacy taskfile + bus
620 master IDE interface. If a controller provides 646 master IDE interface. If a controller provides other better mechanism
621 for error reporting, mapping those into catego 647 for error reporting, mapping those into categories described below
622 shouldn't be difficult. 648 shouldn't be difficult.
623 649
624 In the following sections, two recovery action 650 In the following sections, two recovery actions - reset and
625 reconfiguring transport - are mentioned. These 651 reconfiguring transport - are mentioned. These are described further in
626 `EH recovery actions <#exrec>`__. 652 `EH recovery actions <#exrec>`__.
627 653
628 HSM violation 654 HSM violation
629 ~~~~~~~~~~~~~ 655 ~~~~~~~~~~~~~
630 656
631 This error is indicated when STATUS value does 657 This error is indicated when STATUS value doesn't match HSM requirement
632 during issuing or execution any ATA/ATAPI comm 658 during issuing or execution any ATA/ATAPI command.
633 659
634 - ATA_STATUS doesn't contain !BSY && DRDY && 660 - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to
635 issue a command. 661 issue a command.
636 662
637 - !BSY && !DRQ during PIO data transfer. 663 - !BSY && !DRQ during PIO data transfer.
638 664
639 - DRQ on command completion. 665 - DRQ on command completion.
640 666
641 - !BSY && ERR after CDB transfer starts but b 667 - !BSY && ERR after CDB transfer starts but before the last byte of CDB
642 is transferred. ATA/ATAPI standard states t 668 is transferred. ATA/ATAPI standard states that "The device shall not
643 terminate the PACKET command with an error 669 terminate the PACKET command with an error before the last byte of
644 the command packet has been written" in the 670 the command packet has been written" in the error outputs description
645 of PACKET command and the state diagram doe 671 of PACKET command and the state diagram doesn't include such
646 transitions. 672 transitions.
647 673
648 In these cases, HSM is violated and not much i 674 In these cases, HSM is violated and not much information regarding the
649 error can be acquired from STATUS or ERROR reg 675 error can be acquired from STATUS or ERROR register. IOW, this error can
650 be anything - driver bug, faulty device, contr 676 be anything - driver bug, faulty device, controller and/or cable.
651 677
652 As HSM is violated, reset is necessary to rest 678 As HSM is violated, reset is necessary to restore known state.
653 Reconfiguring transport for lower speed might 679 Reconfiguring transport for lower speed might be helpful too as
654 transmission errors sometimes cause this kind 680 transmission errors sometimes cause this kind of errors.
655 681
656 ATA/ATAPI device error (non-NCQ / non-CHECK CO 682 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
657 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 683 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
658 684
659 These are errors detected and reported by ATA/ 685 These are errors detected and reported by ATA/ATAPI devices indicating
660 device problems. For this type of errors, STAT 686 device problems. For this type of errors, STATUS and ERROR register
661 values are valid and describe error condition. 687 values are valid and describe error condition. Note that some of ATA bus
662 errors are detected by ATA/ATAPI devices and r 688 errors are detected by ATA/ATAPI devices and reported using the same
663 mechanism as device errors. Those cases are de 689 mechanism as device errors. Those cases are described later in this
664 section. 690 section.
665 691
666 For ATA commands, this type of errors are indi 692 For ATA commands, this type of errors are indicated by !BSY && ERR
667 during command execution and on completion. 693 during command execution and on completion.
668 694
669 For ATAPI commands, 695 For ATAPI commands,
670 696
671 - !BSY && ERR && ABRT right after issuing PAC 697 - !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET
672 command is not supported and falls in this 698 command is not supported and falls in this category.
673 699
674 - !BSY && ERR(==CHK) && !ABRT after the last 700 - !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred
675 indicates CHECK CONDITION and doesn't fall 701 indicates CHECK CONDITION and doesn't fall in this category.
676 702
677 - !BSY && ERR(==CHK) && ABRT after the last b 703 - !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred
678 \*probably\* indicates CHECK CONDITION and 704 \*probably\* indicates CHECK CONDITION and doesn't fall in this
679 category. 705 category.
680 706
681 Of errors detected as above, the following are 707 Of errors detected as above, the following are not ATA/ATAPI device
682 errors but ATA bus errors and should be handle 708 errors but ATA bus errors and should be handled according to
683 `ATA bus error <#excatATAbusErr>`__. 709 `ATA bus error <#excatATAbusErr>`__.
684 710
685 CRC error during data transfer 711 CRC error during data transfer
686 This is indicated by ICRC bit in the ERROR 712 This is indicated by ICRC bit in the ERROR register and means that
687 corruption occurred during data transfer. 713 corruption occurred during data transfer. Up to ATA/ATAPI-7, the
688 standard specifies that this bit is only a 714 standard specifies that this bit is only applicable to UDMA
689 transfers but ATA/ATAPI-8 draft revision 1 715 transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be
690 applicable to multiword DMA and PIO. 716 applicable to multiword DMA and PIO.
691 717
692 ABRT error during data transfer or on completi 718 ABRT error during data transfer or on completion
693 Up to ATA/ATAPI-7, the standard specifies 719 Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on
694 ICRC errors and on cases where a device is 720 ICRC errors and on cases where a device is not able to complete a
695 command. Combined with the fact that MWDMA 721 command. Combined with the fact that MWDMA and PIO transfer errors
696 aren't allowed to use ICRC bit up to ATA/A 722 aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply
697 that ABRT bit alone could indicate transfe 723 that ABRT bit alone could indicate transfer errors.
698 724
699 However, ATA/ATAPI-8 draft revision 1f rem 725 However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC
700 errors can turn on ABRT. So, this is kind 726 errors can turn on ABRT. So, this is kind of gray area. Some
701 heuristics are needed here. 727 heuristics are needed here.
702 728
703 ATA/ATAPI device errors can be further categor 729 ATA/ATAPI device errors can be further categorized as follows.
704 730
705 Media errors 731 Media errors
706 This is indicated by UNC bit in the ERROR 732 This is indicated by UNC bit in the ERROR register. ATA devices
707 reports UNC error only after certain numbe 733 reports UNC error only after certain number of retries cannot
708 recover the data, so there's nothing much 734 recover the data, so there's nothing much else to do other than
709 notifying upper layer. 735 notifying upper layer.
710 736
711 READ and WRITE commands report CHS or LBA 737 READ and WRITE commands report CHS or LBA of the first failed sector
712 but ATA/ATAPI standard specifies that the 738 but ATA/ATAPI standard specifies that the amount of transferred data
713 on error completion is indeterminate, so w 739 on error completion is indeterminate, so we cannot assume that
714 sectors preceding the failed sector have b 740 sectors preceding the failed sector have been transferred and thus
715 cannot complete those sectors successfully 741 cannot complete those sectors successfully as SCSI does.
716 742
717 Media changed / media change requested error 743 Media changed / media change requested error
718 <<TODO: fill here>> 744 <<TODO: fill here>>
719 745
720 Address error 746 Address error
721 This is indicated by IDNF bit in the ERROR 747 This is indicated by IDNF bit in the ERROR register. Report to upper
722 layer. 748 layer.
723 749
724 Other errors 750 Other errors
725 This can be invalid command or parameter i 751 This can be invalid command or parameter indicated by ABRT ERROR bit
726 or some other error condition. Note that A 752 or some other error condition. Note that ABRT bit can indicate a lot
727 of things including ICRC and Address error 753 of things including ICRC and Address errors. Heuristics needed.
728 754
729 Depending on commands, not all STATUS/ERROR bi 755 Depending on commands, not all STATUS/ERROR bits are applicable. These
730 non-applicable bits are marked with "na" in th 756 non-applicable bits are marked with "na" in the output descriptions but
731 up to ATA/ATAPI-7 no definition of "na" can be 757 up to ATA/ATAPI-7 no definition of "na" can be found. However,
732 ATA/ATAPI-8 draft revision 1f describes "N/A" 758 ATA/ATAPI-8 draft revision 1f describes "N/A" as follows.
733 759
734 3.2.3.3a N/A 760 3.2.3.3a N/A
735 A keyword the indicates a field has no 761 A keyword the indicates a field has no defined value in this
736 standard and should not be checked by 762 standard and should not be checked by the host or device. N/A
737 fields should be cleared to zero. 763 fields should be cleared to zero.
738 764
739 So, it seems reasonable to assume that "na" bi 765 So, it seems reasonable to assume that "na" bits are cleared to zero by
740 devices and thus need no explicit masking. 766 devices and thus need no explicit masking.
741 767
742 ATAPI device CHECK CONDITION 768 ATAPI device CHECK CONDITION
743 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 769 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
744 770
745 ATAPI device CHECK CONDITION error is indicate 771 ATAPI device CHECK CONDITION error is indicated by set CHK bit (ERR bit)
746 in the STATUS register after the last byte of 772 in the STATUS register after the last byte of CDB is transferred for a
747 PACKET command. For this kind of errors, sense 773 PACKET command. For this kind of errors, sense data should be acquired
748 to gather information regarding the errors. RE 774 to gather information regarding the errors. REQUEST SENSE packet command
749 should be used to acquire sense data. 775 should be used to acquire sense data.
750 776
751 Once sense data is acquired, this type of erro 777 Once sense data is acquired, this type of errors can be handled
752 similarly to other SCSI errors. Note that sens 778 similarly to other SCSI errors. Note that sense data may indicate ATA
753 bus error (e.g. Sense Key 04h HARDWARE ERROR & 779 bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI
754 PARITY ERROR). In such cases, the error should 780 PARITY ERROR). In such cases, the error should be considered as an ATA
755 bus error and handled according to `ATA bus er 781 bus error and handled according to `ATA bus error <#excatATAbusErr>`__.
756 782
757 ATA device error (NCQ) 783 ATA device error (NCQ)
758 ~~~~~~~~~~~~~~~~~~~~~~ 784 ~~~~~~~~~~~~~~~~~~~~~~
759 785
760 NCQ command error is indicated by cleared BSY 786 NCQ command error is indicated by cleared BSY and set ERR bit during NCQ
761 command phase (one or more NCQ commands outsta 787 command phase (one or more NCQ commands outstanding). Although STATUS
762 and ERROR registers will contain valid values 788 and ERROR registers will contain valid values describing the error, READ
763 LOG EXT is required to clear the error conditi 789 LOG EXT is required to clear the error condition, determine which
764 command has failed and acquire more informatio 790 command has failed and acquire more information.
765 791
766 READ LOG EXT Log Page 10h reports which tag ha 792 READ LOG EXT Log Page 10h reports which tag has failed and taskfile
767 register values describing the error. With thi 793 register values describing the error. With this information the failed
768 command can be handled as a normal ATA command 794 command can be handled as a normal ATA command error as in
769 `ATA/ATAPI device error (non-NCQ / non-CHECK C 795 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__
770 and all other in-flight commands must be retri 796 and all other in-flight commands must be retried. Note that this retry
771 should not be counted - it's likely that comma 797 should not be counted - it's likely that commands retried this way would
772 have completed normally if it were not for the 798 have completed normally if it were not for the failed command.
773 799
774 Note that ATA bus errors can be reported as AT 800 Note that ATA bus errors can be reported as ATA device NCQ errors. This
775 should be handled as described in `ATA bus err 801 should be handled as described in `ATA bus error <#excatATAbusErr>`__.
776 802
777 If READ LOG EXT Log Page 10h fails or reports 803 If READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly
778 screwed. This condition should be treated acco 804 screwed. This condition should be treated according to
779 `HSM violation <#excatHSMviolation>`__. 805 `HSM violation <#excatHSMviolation>`__.
780 806
781 ATA bus error 807 ATA bus error
782 ~~~~~~~~~~~~~ 808 ~~~~~~~~~~~~~
783 809
784 ATA bus error means that data corruption occur 810 ATA bus error means that data corruption occurred during transmission
785 over ATA bus (SATA or PATA). This type of erro 811 over ATA bus (SATA or PATA). This type of errors can be indicated by
786 812
787 - ICRC or ABRT error as described in 813 - ICRC or ABRT error as described in
788 `ATA/ATAPI device error (non-NCQ / non-CHEC 814 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__.
789 815
790 - Controller-specific error completion with e 816 - Controller-specific error completion with error information
791 indicating transmission error. 817 indicating transmission error.
792 818
793 - On some controllers, command timeout. In th 819 - On some controllers, command timeout. In this case, there may be a
794 mechanism to determine that the timeout is 820 mechanism to determine that the timeout is due to transmission error.
795 821
796 - Unknown/random errors, timeouts and all sor 822 - Unknown/random errors, timeouts and all sorts of weirdities.
797 823
798 As described above, transmission errors can ca 824 As described above, transmission errors can cause wide variety of
799 symptoms ranging from device ICRC error to ran 825 symptoms ranging from device ICRC error to random device lockup, and,
800 for many cases, there is no way to tell if an 826 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 827 transmission error or not; therefore, it's necessary to employ some kind
802 of heuristic when dealing with errors and time 828 of heuristic when dealing with errors and timeouts. For example,
803 encountering repetitive ABRT errors for known 829 encountering repetitive ABRT errors for known supported command is
804 likely to indicate ATA bus error. 830 likely to indicate ATA bus error.
805 831
806 Once it's determined that ATA bus errors have 832 Once it's determined that ATA bus errors have possibly occurred,
807 lowering ATA bus transmission speed is one of 833 lowering ATA bus transmission speed is one of actions which may
808 alleviate the problem. See `Reconfigure transp 834 alleviate the problem. See `Reconfigure transport <#exrecReconf>`__ for
809 more information. 835 more information.
810 836
811 PCI bus error 837 PCI bus error
812 ~~~~~~~~~~~~~ 838 ~~~~~~~~~~~~~
813 839
814 Data corruption or other failures during trans 840 Data corruption or other failures during transmission over PCI (or other
815 system bus). For standard BMDMA, this is indic 841 system bus). For standard BMDMA, this is indicated by Error bit in the
816 BMDMA Status register. This type of errors mus 842 BMDMA Status register. This type of errors must be logged as it
817 indicates something is very wrong with the sys 843 indicates something is very wrong with the system. Resetting host
818 controller is recommended. 844 controller is recommended.
819 845
820 Late completion 846 Late completion
821 ~~~~~~~~~~~~~~~ 847 ~~~~~~~~~~~~~~~
822 848
823 This occurs when timeout occurs and the timeou 849 This occurs when timeout occurs and the timeout handler finds out that
824 the timed out command has completed successful 850 the timed out command has completed successfully or with error. This is
825 usually caused by lost interrupts. This type o 851 usually caused by lost interrupts. This type of errors must be logged.
826 Resetting host controller is recommended. 852 Resetting host controller is recommended.
827 853
828 Unknown error (timeout) 854 Unknown error (timeout)
829 ~~~~~~~~~~~~~~~~~~~~~~~ 855 ~~~~~~~~~~~~~~~~~~~~~~~
830 856
831 This is when timeout occurs and the command is 857 This is when timeout occurs and the command is still processing or the
832 host and device are in unknown state. When thi 858 host and device are in unknown state. When this occurs, HSM could be in
833 any valid or invalid state. To bring the devic 859 any valid or invalid state. To bring the device to known state and make
834 it forget about the timed out command, resetti 860 it forget about the timed out command, resetting is necessary. The timed
835 out command may be retried. 861 out command may be retried.
836 862
837 Timeouts can also be caused by transmission er 863 Timeouts can also be caused by transmission errors. Refer to
838 `ATA bus error <#excatATAbusErr>`__ for more d 864 `ATA bus error <#excatATAbusErr>`__ for more details.
839 865
840 Hotplug and power management exceptions 866 Hotplug and power management exceptions
841 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 867 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
842 868
843 <<TODO: fill here>> 869 <<TODO: fill here>>
844 870
845 EH recovery actions 871 EH recovery actions
846 ------------------- 872 -------------------
847 873
848 This section discusses several important recov 874 This section discusses several important recovery actions.
849 875
850 Clearing error condition 876 Clearing error condition
851 ~~~~~~~~~~~~~~~~~~~~~~~~ 877 ~~~~~~~~~~~~~~~~~~~~~~~~
852 878
853 Many controllers require its error registers t 879 Many controllers require its error registers to be cleared by error
854 handler. Different controllers may have differ 880 handler. Different controllers may have different requirements.
855 881
856 For SATA, it's strongly recommended to clear a 882 For SATA, it's strongly recommended to clear at least SError register
857 during error handling. 883 during error handling.
858 884
859 Reset 885 Reset
860 ~~~~~ 886 ~~~~~
861 887
862 During EH, resetting is necessary in the follo 888 During EH, resetting is necessary in the following cases.
863 889
864 - HSM is in unknown or invalid state 890 - HSM is in unknown or invalid state
865 891
866 - HBA is in unknown or invalid state 892 - HBA is in unknown or invalid state
867 893
868 - EH needs to make HBA/device forget about in 894 - EH needs to make HBA/device forget about in-flight commands
869 895
870 - HBA/device behaves weirdly 896 - HBA/device behaves weirdly
871 897
872 Resetting during EH might be a good idea regar 898 Resetting during EH might be a good idea regardless of error condition
873 to improve EH robustness. Whether to reset bot 899 to improve EH robustness. Whether to reset both or either one of HBA and
874 device depends on situation but the following 900 device depends on situation but the following scheme is recommended.
875 901
876 - When it's known that HBA is in ready state 902 - When it's known that HBA is in ready state but ATA/ATAPI device is in
877 unknown state, reset only device. 903 unknown state, reset only device.
878 904
879 - If HBA is in unknown state, reset both HBA 905 - If HBA is in unknown state, reset both HBA and device.
880 906
881 HBA resetting is implementation specific. For 907 HBA resetting is implementation specific. For a controller complying to
882 taskfile/BMDMA PCI IDE, stopping active DMA tr 908 taskfile/BMDMA PCI IDE, stopping active DMA transaction may be
883 sufficient iff BMDMA state is the only HBA con 909 sufficient iff BMDMA state is the only HBA context. But even mostly
884 taskfile/BMDMA PCI IDE complying controllers m 910 taskfile/BMDMA PCI IDE complying controllers may have implementation
885 specific requirements and mechanism to reset t 911 specific requirements and mechanism to reset themselves. This must be
886 addressed by specific drivers. 912 addressed by specific drivers.
887 913
888 OTOH, ATA/ATAPI standard describes in detail w 914 OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI
889 devices. 915 devices.
890 916
891 PATA hardware reset 917 PATA hardware reset
892 This is hardware initiated device reset si 918 This is hardware initiated device reset signalled with asserted PATA
893 RESET- signal. There is no standard way to 919 RESET- signal. There is no standard way to initiate hardware reset
894 from software although some hardware provi 920 from software although some hardware provides registers that allow
895 driver to directly tweak the RESET- signal 921 driver to directly tweak the RESET- signal.
896 922
897 Software reset 923 Software reset
898 This is achieved by turning CONTROL SRST b 924 This is achieved by turning CONTROL SRST bit on for at least 5us.
899 Both PATA and SATA support it but, in case 925 Both PATA and SATA support it but, in case of SATA, this may require
900 controller-specific support as the second 926 controller-specific support as the second Register FIS to clear SRST
901 should be transmitted while BSY bit is sti 927 should be transmitted while BSY bit is still set. Note that on PATA,
902 this resets both master and slave devices 928 this resets both master and slave devices on a channel.
903 929
904 EXECUTE DEVICE DIAGNOSTIC command 930 EXECUTE DEVICE DIAGNOSTIC command
905 Although ATA/ATAPI standard doesn't descri 931 Although ATA/ATAPI standard doesn't describe exactly, EDD implies
906 some level of resetting, possibly similar 932 some level of resetting, possibly similar level with software reset.
907 Host-side EDD protocol can be handled with 933 Host-side EDD protocol can be handled with normal command processing
908 and most SATA controllers should be able t 934 and most SATA controllers should be able to handle EDD's just like
909 other commands. As in software reset, EDD 935 other commands. As in software reset, EDD affects both devices on a
910 PATA bus. 936 PATA bus.
911 937
912 Although EDD does reset devices, this does 938 Although EDD does reset devices, this doesn't suit error handling as
913 EDD cannot be issued while BSY is set and 939 EDD cannot be issued while BSY is set and it's unclear how it will
914 act when device is in unknown/weird state. 940 act when device is in unknown/weird state.
915 941
916 ATAPI DEVICE RESET command 942 ATAPI DEVICE RESET command
917 This is very similar to software reset exc 943 This is very similar to software reset except that reset can be
918 restricted to the selected device without 944 restricted to the selected device without affecting the other device
919 sharing the cable. 945 sharing the cable.
920 946
921 SATA phy reset 947 SATA phy reset
922 This is the preferred way of resetting a S 948 This is the preferred way of resetting a SATA device. In effect,
923 it's identical to PATA hardware reset. Not 949 it's identical to PATA hardware reset. Note that this can be done
924 with the standard SCR Control register. As 950 with the standard SCR Control register. As such, it's usually easier
925 to implement than software reset. 951 to implement than software reset.
926 952
927 One more thing to consider when resetting devi 953 One more thing to consider when resetting devices is that resetting
928 clears certain configuration parameters and th 954 clears certain configuration parameters and they need to be set to their
929 previous or newly adjusted values after reset. 955 previous or newly adjusted values after reset.
930 956
931 Parameters affected are. 957 Parameters affected are.
932 958
933 - CHS set up with INITIALIZE DEVICE PARAMETER 959 - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
934 960
935 - Parameters set with SET FEATURES including 961 - Parameters set with SET FEATURES including transfer mode setting
936 962
937 - Block count set with SET MULTIPLE MODE 963 - Block count set with SET MULTIPLE MODE
938 964
939 - Other parameters (SET MAX, MEDIA LOCK...) 965 - Other parameters (SET MAX, MEDIA LOCK...)
940 966
941 ATA/ATAPI standard specifies that some paramet 967 ATA/ATAPI standard specifies that some parameters must be maintained
942 across hardware or software reset, but doesn't 968 across hardware or software reset, but doesn't strictly specify all of
943 them. Always reconfiguring needed parameters a 969 them. Always reconfiguring needed parameters after reset is required for
944 robustness. Note that this also applies when r 970 robustness. Note that this also applies when resuming from deep sleep
945 (power-off). 971 (power-off).
946 972
947 Also, ATA/ATAPI standard requires that IDENTIF 973 Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET
948 DEVICE is issued after any configuration param 974 DEVICE is issued after any configuration parameter is updated or a
949 hardware reset and the result used for further 975 hardware reset and the result used for further operation. OS driver is
950 required to implement revalidation mechanism t 976 required to implement revalidation mechanism to support this.
951 977
952 Reconfigure transport 978 Reconfigure transport
953 ~~~~~~~~~~~~~~~~~~~~~ 979 ~~~~~~~~~~~~~~~~~~~~~
954 980
955 For both PATA and SATA, a lot of corners are c 981 For both PATA and SATA, a lot of corners are cut for cheap connectors,
956 cables or controllers and it's quite common to 982 cables or controllers and it's quite common to see high transmission
957 error rate. This can be mitigated by lowering 983 error rate. This can be mitigated by lowering transmission speed.
958 984
959 The following is a possible scheme Jeff Garzik 985 The following is a possible scheme Jeff Garzik suggested.
960 986
961 If more than $N (3?) transmission errors h 987 If more than $N (3?) transmission errors happen in 15 minutes,
962 988
963 - if SATA, decrease SATA PHY speed. if sp 989 - if SATA, decrease SATA PHY speed. if speed cannot be decreased,
964 990
965 - decrease UDMA xfer speed. if at UDMA0, 991 - decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
966 992
967 - decrease PIO xfer speed. if at PIO3, co 993 - decrease PIO xfer speed. if at PIO3, complain, but continue
968 994
969 ata_piix Internals 995 ata_piix Internals
970 =================== 996 ===================
971 997
972 .. kernel-doc:: drivers/ata/ata_piix.c 998 .. kernel-doc:: drivers/ata/ata_piix.c
973 :internal: 999 :internal:
974 1000
975 sata_sil Internals 1001 sata_sil Internals
976 =================== 1002 ===================
977 1003
978 .. kernel-doc:: drivers/ata/sata_sil.c 1004 .. kernel-doc:: drivers/ata/sata_sil.c
979 :internal: 1005 :internal:
980 1006
981 Thanks 1007 Thanks
982 ====== 1008 ======
983 1009
984 The bulk of the ATA knowledge comes thanks to 1010 The bulk of the ATA knowledge comes thanks to long conversations with
985 Andre Hedrick (www.linux-ide.org), and long ho 1011 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and
986 SCSI specifications. 1012 SCSI specifications.
987 1013
988 Thanks to Alan Cox for pointing out similariti 1014 Thanks to Alan Cox for pointing out similarities between SATA and SCSI,
989 and in general for motivation to hack on libat 1015 and in general for motivation to hack on libata.
990 1016
991 libata's device detection method, ata_pio_devc 1017 libata's device detection method, ata_pio_devchk, and in general all
992 the early probing was based on extensive study 1018 the early probing was based on extensive study of Hale Landis's
993 probe/reset code in his ATADRVR driver (www.at 1019 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.