Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
libata: more docs updates
+57
Documentation/DocBook/libata.tmpl
+57
Documentation/DocBook/libata.tmpl
···
60
60
61
61
<chapter id="libataDriverApi">
62
62
<title>libata Driver API</title>
63
+
<para>
64
+
struct ata_port_operations is defined for every low-level libata
65
+
hardware driver, and it controls how the low-level driver
66
+
interfaces with the ATA and SCSI layers.
67
+
</para>
68
+
<para>
69
+
FIS-based drivers will hook into the system with ->qc_prep() and
70
+
->qc_issue() high-level hooks. Hardware which behaves in a manner
71
+
similar to PCI IDE hardware may utilize several generic helpers,
72
+
defining at a bare minimum the bus I/O addresses of the ATA shadow
73
+
register blocks.
74
+
</para>
63
75
<sect1>
64
76
<title>struct ata_port_operations</title>
65
77
78
+
<sect2><title>Disable ATA port</title>
66
79
<programlisting>
67
80
void (*port_disable) (struct ata_port *);
68
81
</programlisting>
···
86
73
unplug).
87
74
</para>
88
75
76
+
</sect2>
77
+
78
+
<sect2><title>Post-IDENTIFY device configuration</title>
89
79
<programlisting>
90
80
void (*dev_config) (struct ata_port *, struct ata_device *);
91
81
</programlisting>
···
99
83
issue of SET FEATURES - XFER MODE, and prior to operation.
100
84
</para>
101
85
86
+
</sect2>
87
+
88
+
<sect2><title>Set PIO/DMA mode</title>
102
89
<programlisting>
103
90
void (*set_piomode) (struct ata_port *, struct ata_device *);
104
91
void (*set_dmamode) (struct ata_port *, struct ata_device *);
···
122
103
->set_dma_mode() is only called if DMA is possible.
123
104
</para>
124
105
106
+
</sect2>
107
+
108
+
<sect2><title>Taskfile read/write</title>
125
109
<programlisting>
126
110
void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
127
111
void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
···
137
115
taskfile register values.
138
116
</para>
139
117
118
+
</sect2>
119
+
120
+
<sect2><title>ATA command execute</title>
140
121
<programlisting>
141
122
void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
142
123
</programlisting>
···
149
124
->tf_load(), to be initiated in hardware.
150
125
</para>
151
126
127
+
</sect2>
128
+
129
+
<sect2><title>Per-cmd ATAPI DMA capabilities filter</title>
152
130
<programlisting>
153
131
int (*check_atapi_dma) (struct ata_queued_cmd *qc);
154
132
</programlisting>
···
162
134
command.
163
135
</para>
164
136
137
+
</sect2>
138
+
139
+
<sect2><title>Read specific ATA shadow registers</title>
165
140
<programlisting>
166
141
u8 (*check_status)(struct ata_port *ap);
167
142
u8 (*check_altstatus)(struct ata_port *ap);
···
177
146
the side effect of clearing the interrupt condition.
178
147
</para>
179
148
149
+
</sect2>
150
+
151
+
<sect2><title>Select ATA device on bus</title>
180
152
<programlisting>
181
153
void (*dev_select)(struct ata_port *ap, unsigned int device);
182
154
</programlisting>
···
191
157
meaning on FIS-based devices.
192
158
</para>
193
159
160
+
</sect2>
161
+
162
+
<sect2><title>Reset ATA bus</title>
194
163
<programlisting>
195
164
void (*phy_reset) (struct ata_port *ap);
196
165
</programlisting>
···
206
169
functions ata_bus_reset() or sata_phy_reset() for this hook.
207
170
</para>
208
171
172
+
</sect2>
173
+
174
+
<sect2><title>Control PCI IDE BMDMA engine</title>
209
175
<programlisting>
210
176
void (*bmdma_setup) (struct ata_queued_cmd *qc);
211
177
void (*bmdma_start) (struct ata_queued_cmd *qc);
···
228
188
FIS-based drivers.
229
189
</para>
230
190
191
+
</sect2>
192
+
193
+
<sect2><title>High-level taskfile hooks</title>
231
194
<programlisting>
232
195
void (*qc_prep) (struct ata_queued_cmd *qc);
233
196
int (*qc_issue) (struct ata_queued_cmd *qc);
···
251
208
dispatch. More advanced drivers implement their own ->qc_issue.
252
209
</para>
253
210
211
+
</sect2>
212
+
213
+
<sect2><title>Timeout (error) handling</title>
254
214
<programlisting>
255
215
void (*eng_timeout) (struct ata_port *ap);
256
216
</programlisting>
···
265
219
drivers may use the helper function ata_eng_timeout().
266
220
</para>
267
221
222
+
</sect2>
223
+
224
+
<sect2><title>Hardware interrupt handling</title>
268
225
<programlisting>
269
226
irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
270
227
void (*irq_clear) (struct ata_port *);
···
280
231
is quiet.
281
232
</para>
282
233
234
+
</sect2>
235
+
236
+
<sect2><title>SATA phy read/write</title>
283
237
<programlisting>
284
238
u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);
285
239
void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
···
294
242
if ->phy_reset hook called the sata_phy_reset() helper function.
295
243
</para>
296
244
245
+
</sect2>
246
+
247
+
<sect2><title>Init and shutdown</title>
297
248
<programlisting>
298
249
int (*port_start) (struct ata_port *ap);
299
250
void (*port_stop) (struct ata_port *ap);
···
319
264
have completed. The hook must finalize hardware shutdown, release DMA
320
265
and other resources, etc.
321
266
</para>
267
+
268
+
</sect2>
322
269
323
270
</sect1>
324
271
</chapter>