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