1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="libataDevGuide">
6 <bookinfo>
7  <title>libATA Developer's Guide</title>
8  
9  <authorgroup>
10   <author>
11    <firstname>Jeff</firstname>
12    <surname>Garzik</surname>
13   </author>
14  </authorgroup>
15
16  <copyright>
17   <year>2003-2006</year>
18   <holder>Jeff Garzik</holder>
19  </copyright>
20
21  <legalnotice>
22   <para>
23   The contents of this file are subject to the Open
24   Software License version 1.1 that can be found at
25   <ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink>
26   and is included herein by reference.
27   </para>
28
29   <para>
30   Alternatively, the contents of this file may be used under the terms
31   of the GNU General Public License version 2 (the "GPL") as distributed
32   in the kernel source COPYING file, in which case the provisions of
33   the GPL are applicable instead of the above.  If you wish to allow
34   the use of your version of this file only under the terms of the
35   GPL and not to allow others to use your version of this file under
36   the OSL, indicate your decision by deleting the provisions above and
37   replace them with the notice and other provisions required by the GPL.
38   If you do not delete the provisions above, a recipient may use your
39   version of this file under either the OSL or the GPL.
40   </para>
41
42  </legalnotice>
43 </bookinfo>
44
45<toc></toc>
46
47  <chapter id="libataIntroduction">
48     <title>Introduction</title>
49  <para>
50  libATA is a library used inside the Linux kernel to support ATA host
51  controllers and devices.  libATA provides an ATA driver API, class
52  transports for ATA and ATAPI devices, and SCSI&lt;-&gt;ATA translation
53  for ATA devices according to the T10 SAT specification.
54  </para>
55  <para>
56  This Guide documents the libATA driver API, library functions, library
57  internals, and a couple sample ATA low-level drivers.
58  </para>
59  </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>
80void (*port_disable) (struct ata_port *);
81	</programlisting>
82
83	<para>
84	Called from ata_bus_probe() error path, as well as when
85	unregistering from the SCSI module (rmmod, hot unplug).
86	This function should do whatever needs to be done to take the
87	port out of use.  In most cases, ata_port_disable() can be used
88	as this hook.
89	</para>
90	<para>
91	Called from ata_bus_probe() on a failed probe.
92	Called from ata_scsi_release().
93	</para>
94
95	</sect2>
96
97	<sect2><title>Post-IDENTIFY device configuration</title>
98	<programlisting>
99void (*dev_config) (struct ata_port *, struct ata_device *);
100	</programlisting>
101
102	<para>
103	Called after IDENTIFY [PACKET] DEVICE is issued to each device
104	found.  Typically used to apply device-specific fixups prior to
105	issue of SET FEATURES - XFER MODE, and prior to operation.
106	</para>
107	<para>
108	This entry may be specified as NULL in ata_port_operations.
109	</para>
110
111	</sect2>
112
113	<sect2><title>Set PIO/DMA mode</title>
114	<programlisting>
115void (*set_piomode) (struct ata_port *, struct ata_device *);
116void (*set_dmamode) (struct ata_port *, struct ata_device *);
117void (*post_set_mode) (struct ata_port *);
118unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);
119	</programlisting>
120
121	<para>
122	Hooks called prior to the issue of SET FEATURES - XFER MODE
123	command.  The optional ->mode_filter() hook is called when libata
124	has built a mask of the possible modes. This is passed to the 
125	->mode_filter() function which should return a mask of valid modes
126	after filtering those unsuitable due to hardware limits. It is not
127	valid to use this interface to add modes.
128	</para>
129	<para>
130	dev->pio_mode and dev->dma_mode are guaranteed to be valid when
131	->set_piomode() and when ->set_dmamode() is called. The timings for
132	any other drive sharing the cable will also be valid at this point.
133	That is the library records the decisions for the modes of each
134	drive on a channel before it attempts to set any of them.
135	</para>
136	<para>
137	->post_set_mode() is
138	called unconditionally, after the SET FEATURES - XFER MODE
139	command completes successfully.
140	</para>
141
142	<para>
143	->set_piomode() is always called (if present), but
144	->set_dma_mode() is only called if DMA is possible.
145	</para>
146
147	</sect2>
148
149	<sect2><title>Taskfile read/write</title>
150	<programlisting>
151void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
152void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
153	</programlisting>
154
155	<para>
156	->tf_load() is called to load the given taskfile into hardware
157	registers / DMA buffers.  ->tf_read() is called to read the
158	hardware registers / DMA buffers, to obtain the current set of
159	taskfile register values.
160	Most drivers for taskfile-based hardware (PIO or MMIO) use
161	ata_sff_tf_load() and ata_sff_tf_read() for these hooks.
162	</para>
163
164	</sect2>
165
166	<sect2><title>PIO data read/write</title>
167	<programlisting>
168void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
169	</programlisting>
170
171	<para>
172All bmdma-style drivers must implement this hook.  This is the low-level
173operation that actually copies the data bytes during a PIO data
174transfer.
175Typically the driver will choose one of ata_sff_data_xfer_noirq(),
176ata_sff_data_xfer(), or ata_sff_data_xfer32().
177	</para>
178
179	</sect2>
180
181	<sect2><title>ATA command execute</title>
182	<programlisting>
183void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
184	</programlisting>
185
186	<para>
187	causes an ATA command, previously loaded with
188	->tf_load(), to be initiated in hardware.
189	Most drivers for taskfile-based hardware use ata_sff_exec_command()
190	for this hook.
191	</para>
192
193	</sect2>
194
195	<sect2><title>Per-cmd ATAPI DMA capabilities filter</title>
196	<programlisting>
197int (*check_atapi_dma) (struct ata_queued_cmd *qc);
198	</programlisting>
199
200	<para>
201Allow low-level driver to filter ATA PACKET commands, returning a status
202indicating whether or not it is OK to use DMA for the supplied PACKET
203command.
204	</para>
205	<para>
206	This hook may be specified as NULL, in which case libata will
207	assume that atapi dma can be supported.
208	</para>
209
210	</sect2>
211
212	<sect2><title>Read specific ATA shadow registers</title>
213	<programlisting>
214u8   (*sff_check_status)(struct ata_port *ap);
215u8   (*sff_check_altstatus)(struct ata_port *ap);
216	</programlisting>
217
218	<para>
219	Reads the Status/AltStatus ATA shadow register from
220	hardware.  On some hardware, reading the Status register has
221	the side effect of clearing the interrupt condition.
222	Most drivers for taskfile-based hardware use
223	ata_sff_check_status() for this hook.
224	</para>
225
226	</sect2>
227
228	<sect2><title>Write specific ATA shadow register</title>
229	<programlisting>
230void (*sff_set_devctl)(struct ata_port *ap, u8 ctl);
231	</programlisting>
232
233	<para>
234	Write the device control ATA shadow register to the hardware.
235	Most drivers don't need to define this.
236	</para>
237
238	</sect2>
239
240	<sect2><title>Select ATA device on bus</title>
241	<programlisting>
242void (*sff_dev_select)(struct ata_port *ap, unsigned int device);
243	</programlisting>
244
245	<para>
246	Issues the low-level hardware command(s) that causes one of N
247	hardware devices to be considered 'selected' (active and
248	available for use) on the ATA bus.  This generally has no
249	meaning on FIS-based devices.
250	</para>
251	<para>
252	Most drivers for taskfile-based hardware use
253	ata_sff_dev_select() for this hook.
254	</para>
255
256	</sect2>
257
258	<sect2><title>Private tuning method</title>
259	<programlisting>
260void (*set_mode) (struct ata_port *ap);
261	</programlisting>
262
263	<para>
264	By default libata performs drive and controller tuning in
265	accordance with the ATA timing rules and also applies blacklists
266	and cable limits. Some controllers need special handling and have
267	custom tuning rules, typically raid controllers that use ATA
268	commands but do not actually do drive timing.
269	</para>
270
271	<warning>
272	<para>
273	This hook should not be used to replace the standard controller
274	tuning logic when a controller has quirks. Replacing the default
275	tuning logic in that case would bypass handling for drive and
276	bridge quirks that may be important to data reliability. If a
277	controller needs to filter the mode selection it should use the
278	mode_filter hook instead.
279	</para>
280	</warning>
281
282	</sect2>
283
284	<sect2><title>Control PCI IDE BMDMA engine</title>
285	<programlisting>
286void (*bmdma_setup) (struct ata_queued_cmd *qc);
287void (*bmdma_start) (struct ata_queued_cmd *qc);
288void (*bmdma_stop) (struct ata_port *ap);
289u8   (*bmdma_status) (struct ata_port *ap);
290	</programlisting>
291
292	<para>
293When setting up an IDE BMDMA transaction, these hooks arm
294(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
295the hardware's DMA engine.  ->bmdma_status is used to read the standard
296PCI IDE DMA Status register.
297	</para>
298
299	<para>
300These hooks are typically either no-ops, or simply not implemented, in
301FIS-based drivers.
302	</para>
303	<para>
304Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
305hook.  ata_bmdma_setup() will write the pointer to the PRD table to
306the IDE PRD Table Address register, enable DMA in the DMA Command
307register, and call exec_command() to begin the transfer.
308	</para>
309	<para>
310Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
311hook.  ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
312Command register.
313	</para>
314	<para>
315Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
316hook.  ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
317command register.
318	</para>
319	<para>
320Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.
321	</para>
322
323	</sect2>
324
325	<sect2><title>High-level taskfile hooks</title>
326	<programlisting>
327void (*qc_prep) (struct ata_queued_cmd *qc);
328int (*qc_issue) (struct ata_queued_cmd *qc);
329	</programlisting>
330
331	<para>
332	Higher-level hooks, these two hooks can potentially supercede
333	several of the above taskfile/DMA engine hooks.  ->qc_prep is
334	called after the buffers have been DMA-mapped, and is typically
335	used to populate the hardware's DMA scatter-gather table.
336	Most drivers use the standard ata_qc_prep() helper function, but
337	more advanced drivers roll their own.
338	</para>
339	<para>
340	->qc_issue is used to make a command active, once the hardware
341	and S/G tables have been prepared.  IDE BMDMA drivers use the
342	helper function ata_qc_issue_prot() for taskfile protocol-based
343	dispatch.  More advanced drivers implement their own ->qc_issue.
344	</para>
345	<para>
346	ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
347	->bmdma_start() as necessary to initiate a transfer.
348	</para>
349
350	</sect2>
351
352	<sect2><title>Exception and probe handling (EH)</title>
353	<programlisting>
354void (*eng_timeout) (struct ata_port *ap);
355void (*phy_reset) (struct ata_port *ap);
356	</programlisting>
357
358	<para>
359Deprecated.  Use ->error_handler() instead.
360	</para>
361
362	<programlisting>
363void (*freeze) (struct ata_port *ap);
364void (*thaw) (struct ata_port *ap);
365	</programlisting>
366
367	<para>
368ata_port_freeze() is called when HSM violations or some other
369condition disrupts normal operation of the port.  A frozen port
370is not allowed to perform any operation until the port is
371thawed, which usually follows a successful reset.
372	</para>
373
374	<para>
375The optional ->freeze() callback can be used for freezing the port
376hardware-wise (e.g. mask interrupt and stop DMA engine).  If a
377port cannot be frozen hardware-wise, the interrupt handler
378must ack and clear interrupts unconditionally while the port
379is frozen.
380	</para>
381	<para>
382The optional ->thaw() callback is called to perform the opposite of ->freeze():
383prepare the port for normal operation once again.  Unmask interrupts,
384start DMA engine, etc.
385	</para>
386
387	<programlisting>
388void (*error_handler) (struct ata_port *ap);
389	</programlisting>
390
391	<para>
392->error_handler() is a driver's hook into probe, hotplug, and recovery
393and other exceptional conditions.  The primary responsibility of an
394implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set
395of EH hooks as arguments:
396	</para>
397
398	<para>
399'prereset' hook (may be NULL) is called during an EH reset, before any other actions
400are taken.
401	</para>
402
403	<para>
404'postreset' hook (may be NULL) is called after the EH reset is performed.  Based on
405existing conditions, severity of the problem, and hardware capabilities,
406	</para>
407
408	<para>
409Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
410called to perform the low-level EH reset.
411	</para>
412
413	<programlisting>
414void (*post_internal_cmd) (struct ata_queued_cmd *qc);
415	</programlisting>
416
417	<para>
418Perform any hardware-specific actions necessary to finish processing
419after executing a probe-time or EH-time command via ata_exec_internal().
420	</para>
421
422	</sect2>
423
424	<sect2><title>Hardware interrupt handling</title>
425	<programlisting>
426irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
427void (*irq_clear) (struct ata_port *);
428	</programlisting>
429
430	<para>
431	->irq_handler is the interrupt handling routine registered with
432	the system, by libata.  ->irq_clear is called during probe just
433	before the interrupt handler is registered, to be sure hardware
434	is quiet.
435	</para>
436	<para>
437	The second argument, dev_instance, should be cast to a pointer
438	to struct ata_host_set.
439	</para>
440	<para>
441	Most legacy IDE drivers use ata_sff_interrupt() for the
442	irq_handler hook, which scans all ports in the host_set,
443	determines which queued command was active (if any), and calls
444	ata_sff_host_intr(ap,qc).
445	</para>
446	<para>
447	Most legacy IDE drivers use ata_sff_irq_clear() for the
448	irq_clear() hook, which simply clears the interrupt and error
449	flags in the DMA status register.
450	</para>
451
452	</sect2>
453
454	<sect2><title>SATA phy read/write</title>
455	<programlisting>
456int (*scr_read) (struct ata_port *ap, unsigned int sc_reg,
457		 u32 *val);
458int (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
459                   u32 val);
460	</programlisting>
461
462	<para>
463	Read and write standard SATA phy registers.  Currently only used
464	if ->phy_reset hook called the sata_phy_reset() helper function.
465	sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
466	</para>
467
468	</sect2>
469
470	<sect2><title>Init and shutdown</title>
471	<programlisting>
472int (*port_start) (struct ata_port *ap);
473void (*port_stop) (struct ata_port *ap);
474void (*host_stop) (struct ata_host_set *host_set);
475	</programlisting>
476
477	<para>
478	->port_start() is called just after the data structures for each
479	port are initialized.  Typically this is used to alloc per-port
480	DMA buffers / tables / rings, enable DMA engines, and similar
481	tasks.  Some drivers also use this entry point as a chance to
482	allocate driver-private memory for ap->private_data.
483	</para>
484	<para>
485	Many drivers use ata_port_start() as this hook or call
486	it from their own port_start() hooks.  ata_port_start()
487	allocates space for a legacy IDE PRD table and returns.
488	</para>
489	<para>
490	->port_stop() is called after ->host_stop().  Its sole function
491	is to release DMA/memory resources, now that they are no longer
492	actively being used.  Many drivers also free driver-private
493	data from port at this time.
494	</para>
495	<para>
496	->host_stop() is called after all ->port_stop() calls
497have completed.  The hook must finalize hardware shutdown, release DMA
498and other resources, etc.
499	This hook may be specified as NULL, in which case it is not called.
500	</para>
501
502	</sect2>
503
504     </sect1>
505  </chapter>
506
507  <chapter id="libataEH">
508        <title>Error handling</title>
509
510	<para>
511	This chapter describes how errors are handled under libata.
512	Readers are advised to read SCSI EH
513	(Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first.
514	</para>
515
516	<sect1><title>Origins of commands</title>
517	<para>
518	In libata, a command is represented with struct ata_queued_cmd
519	or qc.  qc's are preallocated during port initialization and
520	repetitively used for command executions.  Currently only one
521	qc is allocated per port but yet-to-be-merged NCQ branch
522	allocates one for each tag and maps each qc to NCQ tag 1-to-1.
523	</para>
524	<para>
525	libata commands can originate from two sources - libata itself
526	and SCSI midlayer.  libata internal commands are used for
527	initialization and error handling.  All normal blk requests
528	and commands for SCSI emulation are passed as SCSI commands
529	through queuecommand callback of SCSI host template.
530	</para>
531	</sect1>
532
533	<sect1><title>How commands are issued</title>
534
535	<variablelist>
536
537	<varlistentry><term>Internal commands</term>
538	<listitem>
539	<para>
540	First, qc is allocated and initialized using
541	ata_qc_new_init().  Although ata_qc_new_init() doesn't
542	implement any wait or retry mechanism when qc is not
543	available, internal commands are currently issued only during
544	initialization and error recovery, so no other command is
545	active and allocation is guaranteed to succeed.
546	</para>
547	<para>
548	Once allocated qc's taskfile is initialized for the command to
549	be executed.  qc currently has two mechanisms to notify
550	completion.  One is via qc->complete_fn() callback and the
551	other is completion qc->waiting.  qc->complete_fn() callback
552	is the asynchronous path used by normal SCSI translated
553	commands and qc->waiting is the synchronous (issuer sleeps in
554	process context) path used by internal commands.
555	</para>
556	<para>
557	Once initialization is complete, host_set lock is acquired
558	and the qc is issued.
559	</para>
560	</listitem>
561	</varlistentry>
562
563	<varlistentry><term>SCSI commands</term>
564	<listitem>
565	<para>
566	All libata drivers use ata_scsi_queuecmd() as
567	hostt->queuecommand callback.  scmds can either be simulated
568	or translated.  No qc is involved in processing a simulated
569	scmd.  The result is computed right away and the scmd is
570	completed.
571	</para>
572	<para>
573	For a translated scmd, ata_qc_new_init() is invoked to
574	allocate a qc and the scmd is translated into the qc.  SCSI
575	midlayer's completion notification function pointer is stored
576	into qc->scsidone.
577	</para>
578	<para>
579	qc->complete_fn() callback is used for completion
580	notification.  ATA commands use ata_scsi_qc_complete() while
581	ATAPI commands use atapi_qc_complete().  Both functions end up
582	calling qc->scsidone to notify upper layer when the qc is
583	finished.  After translation is completed, the qc is issued
584	with ata_qc_issue().
585	</para>
586	<para>
587	Note that SCSI midlayer invokes hostt->queuecommand while
588	holding host_set lock, so all above occur while holding
589	host_set lock.
590	</para>
591	</listitem>
592	</varlistentry>
593
594	</variablelist>
595	</sect1>
596
597	<sect1><title>How commands are processed</title>
598	<para>
599	Depending on which protocol and which controller are used,
600	commands are processed differently.  For the purpose of
601	discussion, a controller which uses taskfile interface and all
602	standard callbacks is assumed.
603	</para>
604	<para>
605	Currently 6 ATA command protocols are used.  They can be
606	sorted into the following four categories according to how
607	they are processed.
608	</para>
609
610	<variablelist>
611	   <varlistentry><term>ATA NO DATA or DMA</term>
612	   <listitem>
613	   <para>
614	   ATA_PROT_NODATA and ATA_PROT_DMA fall into this category.
615	   These types of commands don't require any software
616	   intervention once issued.  Device will raise interrupt on
617	   completion.
618	   </para>
619	   </listitem>
620	   </varlistentry>
621
622	   <varlistentry><term>ATA PIO</term>
623	   <listitem>
624	   <para>
625	   ATA_PROT_PIO is in this category.  libata currently
626	   implements PIO with polling.  ATA_NIEN bit is set to turn
627	   off interrupt and pio_task on ata_wq performs polling and
628	   IO.
629	   </para>
630	   </listitem>
631	   </varlistentry>
632
633	   <varlistentry><term>ATAPI NODATA or DMA</term>
634	   <listitem>
635	   <para>
636	   ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this
637	   category.  packet_task is used to poll BSY bit after
638	   issuing PACKET command.  Once BSY is turned off by the
639	   device, packet_task transfers CDB and hands off processing
640	   to interrupt handler.
641	   </para>
642	   </listitem>
643	   </varlistentry>
644
645	   <varlistentry><term>ATAPI PIO</term>
646	   <listitem>
647	   <para>
648	   ATA_PROT_ATAPI is in this category.  ATA_NIEN bit is set
649	   and, as in ATAPI NODATA or DMA, packet_task submits cdb.
650	   However, after submitting cdb, further processing (data
651	   transfer) is handed off to pio_task.
652	   </para>
653	   </listitem>
654	   </varlistentry>
655	</variablelist>
656        </sect1>
657
658	<sect1><title>How commands are completed</title>
659	<para>
660	Once issued, all qc's are either completed with
661	ata_qc_complete() or time out.  For commands which are handled
662	by interrupts, ata_host_intr() invokes ata_qc_complete(), and,
663	for PIO tasks, pio_task invokes ata_qc_complete().  In error
664	cases, packet_task may also complete commands.
665	</para>
666	<para>
667	ata_qc_complete() does the following.
668	</para>
669
670	<orderedlist>
671
672	<listitem>
673	<para>
674	DMA memory is unmapped.
675	</para>
676	</listitem>
677
678	<listitem>
679	<para>
680	ATA_QCFLAG_ACTIVE is cleared from qc->flags.
681	</para>
682	</listitem>
683
684	<listitem>
685	<para>
686	qc->complete_fn() callback is invoked.  If the return value of
687	the callback is not zero.  Completion is short circuited and
688	ata_qc_complete() returns.
689	</para>
690	</listitem>
691
692	<listitem>
693	<para>
694	__ata_qc_complete() is called, which does
695	   <orderedlist>
696
697	   <listitem>
698	   <para>
699	   qc->flags is cleared to zero.
700	   </para>
701	   </listitem>
702
703	   <listitem>
704	   <para>
705	   ap->active_tag and qc->tag are poisoned.
706	   </para>
707	   </listitem>
708
709	   <listitem>
710	   <para>
711	   qc->waiting is cleared &amp; completed (in that order).
712	   </para>
713	   </listitem>
714
715	   <listitem>
716	   <para>
717	   qc is deallocated by clearing appropriate bit in ap->qactive.
718	   </para>
719	   </listitem>
720
721	   </orderedlist>
722	</para>
723	</listitem>
724
725	</orderedlist>
726
727	<para>
728	So, it basically notifies upper layer and deallocates qc.  One
729	exception is short-circuit path in #3 which is used by
730	atapi_qc_complete().
731	</para>
732	<para>
733	For all non-ATAPI commands, whether it fails or not, almost
734	the same code path is taken and very little error handling
735	takes place.  A qc is completed with success status if it
736	succeeded, with failed status otherwise.
737	</para>
738	<para>
739	However, failed ATAPI commands require more handling as
740	REQUEST SENSE is needed to acquire sense data.  If an ATAPI
741	command fails, ata_qc_complete() is invoked with error status,
742	which in turn invokes atapi_qc_complete() via
743	qc->complete_fn() callback.
744	</para>
745	<para>
746	This makes atapi_qc_complete() set scmd->result to
747	SAM_STAT_CHECK_CONDITION, complete the scmd and return 1.  As
748	the sense data is empty but scmd->result is CHECK CONDITION,
749	SCSI midlayer will invoke EH for the scmd, and returning 1
750	makes ata_qc_complete() to return without deallocating the qc.
751	This leads us to ata_scsi_error() with partially completed qc.
752	</para>
753
754	</sect1>
755
756	<sect1><title>ata_scsi_error()</title>
757	<para>
758	ata_scsi_error() is the current transportt->eh_strategy_handler()
759	for libata.  As discussed above, this will be entered in two
760	cases - timeout and ATAPI error completion.  This function
761	calls low level libata driver's eng_timeout() callback, the
762	standard callback for which is ata_eng_timeout().  It checks
763	if a qc is active and calls ata_qc_timeout() on the qc if so.
764	Actual error handling occurs in ata_qc_timeout().
765	</para>
766	<para>
767	If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and
768	completes the qc.  Note that as we're currently in EH, we
769	cannot call scsi_done.  As described in SCSI EH doc, a
770	recovered scmd should be either retried with
771	scsi_queue_insert() or finished with scsi_finish_command().
772	Here, we override qc->scsidone with scsi_finish_command() and
773	calls ata_qc_complete().
774	</para>
775	<para>
776	If EH is invoked due to a failed ATAPI qc, the qc here is
777	completed but not deallocated.  The purpose of this
778	half-completion is to use the qc as place holder to make EH
779	code reach this place.  This is a bit hackish, but it works.
780	</para>
781	<para>
782	Once control reaches here, the qc is deallocated by invoking
783	__ata_qc_complete() explicitly.  Then, internal qc for REQUEST
784	SENSE is issued.  Once sense data is acquired, scmd is
785	finished by directly invoking scsi_finish_command() on the
786	scmd.  Note that as we already have completed and deallocated
787	the qc which was associated with the scmd, we don't need
788	to/cannot call ata_qc_complete() again.
789	</para>
790
791	</sect1>
792
793	<sect1><title>Problems with the current EH</title>
794
795	<itemizedlist>
796
797	<listitem>
798	<para>
799	Error representation is too crude.  Currently any and all
800	error conditions are represented with ATA STATUS and ERROR
801	registers.  Errors which aren't ATA device errors are treated
802	as ATA device errors by setting ATA_ERR bit.  Better error
803	descriptor which can properly represent ATA and other
804	errors/exceptions is needed.
805	</para>
806	</listitem>
807
808	<listitem>
809	<para>
810	When handling timeouts, no action is taken to make device
811	forget about the timed out command and ready for new commands.
812	</para>
813	</listitem>
814
815	<listitem>
816	<para>
817	EH handling via ata_scsi_error() is not properly protected
818	from usual command processing.  On EH entrance, the device is
819	not in quiescent state.  Timed out commands may succeed or
820	fail any time.  pio_task and atapi_task may still be running.
821	</para>
822	</listitem>
823
824	<listitem>
825	<para>
826	Too weak error recovery.  Devices / controllers causing HSM
827	mismatch errors and other errors quite often require reset to
828	return to known state.  Also, advanced error handling is
829	necessary to support features like NCQ and hotplug.
830	</para>
831	</listitem>
832
833	<listitem>
834	<para>
835	ATA errors are directly handled in the interrupt handler and
836	PIO errors in pio_task.  This is problematic for advanced
837	error handling for the following reasons.
838	</para>
839	<para>
840	First, advanced error handling often requires context and
841	internal qc execution.
842	</para>
843	<para>
844	Second, even a simple failure (say, CRC error) needs
845	information gathering and could trigger complex error handling
846	(say, resetting &amp; reconfiguring).  Having multiple code
847	paths to gather information, enter EH and trigger actions
848	makes life painful.
849	</para>
850	<para>
851	Third, scattered EH code makes implementing low level drivers
852	difficult.  Low level drivers override libata callbacks.  If
853	EH is scattered over several places, each affected callbacks
854	should perform its part of error handling.  This can be error
855	prone and painful.
856	</para>
857	</listitem>
858
859	</itemizedlist>
860	</sect1>
861  </chapter>
862
863  <chapter id="libataExt">
864     <title>libata Library</title>
865<!-- drivers/ata/libata-core.c -->
866<refentry id="API-ata-link-next">
867<refentryinfo>
868 <title>LINUX</title>
869 <productname>Kernel Hackers Manual</productname>
870 <date>July 2017</date>
871</refentryinfo>
872<refmeta>
873 <refentrytitle><phrase>ata_link_next</phrase></refentrytitle>
874 <manvolnum>9</manvolnum>
875 <refmiscinfo class="version">4.1.27</refmiscinfo>
876</refmeta>
877<refnamediv>
878 <refname>ata_link_next</refname>
879 <refpurpose>
880  link iteration helper
881 </refpurpose>
882</refnamediv>
883<refsynopsisdiv>
884 <title>Synopsis</title>
885  <funcsynopsis><funcprototype>
886   <funcdef>struct ata_link * <function>ata_link_next </function></funcdef>
887   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
888   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
889   <paramdef>enum ata_link_iter_mode <parameter>mode</parameter></paramdef>
890  </funcprototype></funcsynopsis>
891</refsynopsisdiv>
892<refsect1>
893 <title>Arguments</title>
894 <variablelist>
895  <varlistentry>
896   <term><parameter>link</parameter></term>
897   <listitem>
898    <para>
899     the previous link, NULL to start
900    </para>
901   </listitem>
902  </varlistentry>
903  <varlistentry>
904   <term><parameter>ap</parameter></term>
905   <listitem>
906    <para>
907     ATA port containing links to iterate
908    </para>
909   </listitem>
910  </varlistentry>
911  <varlistentry>
912   <term><parameter>mode</parameter></term>
913   <listitem>
914    <para>
915     iteration mode, one of ATA_LITER_*
916    </para>
917   </listitem>
918  </varlistentry>
919 </variablelist>
920</refsect1>
921<refsect1>
922<title>LOCKING</title>
923<para>
924   Host lock or EH context.
925</para>
926</refsect1>
927<refsect1>
928<title>RETURNS</title>
929<para>
930   Pointer to the next link.
931</para>
932</refsect1>
933</refentry>
934
935<refentry id="API-ata-dev-next">
936<refentryinfo>
937 <title>LINUX</title>
938 <productname>Kernel Hackers Manual</productname>
939 <date>July 2017</date>
940</refentryinfo>
941<refmeta>
942 <refentrytitle><phrase>ata_dev_next</phrase></refentrytitle>
943 <manvolnum>9</manvolnum>
944 <refmiscinfo class="version">4.1.27</refmiscinfo>
945</refmeta>
946<refnamediv>
947 <refname>ata_dev_next</refname>
948 <refpurpose>
949     device iteration helper
950 </refpurpose>
951</refnamediv>
952<refsynopsisdiv>
953 <title>Synopsis</title>
954  <funcsynopsis><funcprototype>
955   <funcdef>struct ata_device * <function>ata_dev_next </function></funcdef>
956   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
957   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
958   <paramdef>enum ata_dev_iter_mode <parameter>mode</parameter></paramdef>
959  </funcprototype></funcsynopsis>
960</refsynopsisdiv>
961<refsect1>
962 <title>Arguments</title>
963 <variablelist>
964  <varlistentry>
965   <term><parameter>dev</parameter></term>
966   <listitem>
967    <para>
968     the previous device, NULL to start
969    </para>
970   </listitem>
971  </varlistentry>
972  <varlistentry>
973   <term><parameter>link</parameter></term>
974   <listitem>
975    <para>
976     ATA link containing devices to iterate
977    </para>
978   </listitem>
979  </varlistentry>
980  <varlistentry>
981   <term><parameter>mode</parameter></term>
982   <listitem>
983    <para>
984     iteration mode, one of ATA_DITER_*
985    </para>
986   </listitem>
987  </varlistentry>
988 </variablelist>
989</refsect1>
990<refsect1>
991<title>LOCKING</title>
992<para>
993   Host lock or EH context.
994</para>
995</refsect1>
996<refsect1>
997<title>RETURNS</title>
998<para>
999   Pointer to the next device.
1000</para>
1001</refsect1>
1002</refentry>
1003
1004<refentry id="API-atapi-cmd-type">
1005<refentryinfo>
1006 <title>LINUX</title>
1007 <productname>Kernel Hackers Manual</productname>
1008 <date>July 2017</date>
1009</refentryinfo>
1010<refmeta>
1011 <refentrytitle><phrase>atapi_cmd_type</phrase></refentrytitle>
1012 <manvolnum>9</manvolnum>
1013 <refmiscinfo class="version">4.1.27</refmiscinfo>
1014</refmeta>
1015<refnamediv>
1016 <refname>atapi_cmd_type</refname>
1017 <refpurpose>
1018     Determine ATAPI command type from SCSI opcode
1019 </refpurpose>
1020</refnamediv>
1021<refsynopsisdiv>
1022 <title>Synopsis</title>
1023  <funcsynopsis><funcprototype>
1024   <funcdef>int <function>atapi_cmd_type </function></funcdef>
1025   <paramdef>u8 <parameter>opcode</parameter></paramdef>
1026  </funcprototype></funcsynopsis>
1027</refsynopsisdiv>
1028<refsect1>
1029 <title>Arguments</title>
1030 <variablelist>
1031  <varlistentry>
1032   <term><parameter>opcode</parameter></term>
1033   <listitem>
1034    <para>
1035     SCSI opcode
1036    </para>
1037   </listitem>
1038  </varlistentry>
1039 </variablelist>
1040</refsect1>
1041<refsect1>
1042<title>Description</title>
1043<para>
1044   Determine ATAPI command type from <parameter>opcode</parameter>.
1045</para>
1046</refsect1>
1047<refsect1>
1048<title>LOCKING</title>
1049<para>
1050   None.
1051</para>
1052</refsect1>
1053<refsect1>
1054<title>RETURNS</title>
1055<para>
1056   ATAPI_{READ|WRITE|READ_CD|PASS_THRU|MISC}
1057</para>
1058</refsect1>
1059</refentry>
1060
1061<refentry id="API-ata-tf-to-fis">
1062<refentryinfo>
1063 <title>LINUX</title>
1064 <productname>Kernel Hackers Manual</productname>
1065 <date>July 2017</date>
1066</refentryinfo>
1067<refmeta>
1068 <refentrytitle><phrase>ata_tf_to_fis</phrase></refentrytitle>
1069 <manvolnum>9</manvolnum>
1070 <refmiscinfo class="version">4.1.27</refmiscinfo>
1071</refmeta>
1072<refnamediv>
1073 <refname>ata_tf_to_fis</refname>
1074 <refpurpose>
1075     Convert ATA taskfile to SATA FIS structure
1076 </refpurpose>
1077</refnamediv>
1078<refsynopsisdiv>
1079 <title>Synopsis</title>
1080  <funcsynopsis><funcprototype>
1081   <funcdef>void <function>ata_tf_to_fis </function></funcdef>
1082   <paramdef>const struct ata_taskfile * <parameter>tf</parameter></paramdef>
1083   <paramdef>u8 <parameter>pmp</parameter></paramdef>
1084   <paramdef>int <parameter>is_cmd</parameter></paramdef>
1085   <paramdef>u8 * <parameter>fis</parameter></paramdef>
1086  </funcprototype></funcsynopsis>
1087</refsynopsisdiv>
1088<refsect1>
1089 <title>Arguments</title>
1090 <variablelist>
1091  <varlistentry>
1092   <term><parameter>tf</parameter></term>
1093   <listitem>
1094    <para>
1095     Taskfile to convert
1096    </para>
1097   </listitem>
1098  </varlistentry>
1099  <varlistentry>
1100   <term><parameter>pmp</parameter></term>
1101   <listitem>
1102    <para>
1103     Port multiplier port
1104    </para>
1105   </listitem>
1106  </varlistentry>
1107  <varlistentry>
1108   <term><parameter>is_cmd</parameter></term>
1109   <listitem>
1110    <para>
1111     This FIS is for command
1112    </para>
1113   </listitem>
1114  </varlistentry>
1115  <varlistentry>
1116   <term><parameter>fis</parameter></term>
1117   <listitem>
1118    <para>
1119     Buffer into which data will output
1120    </para>
1121   </listitem>
1122  </varlistentry>
1123 </variablelist>
1124</refsect1>
1125<refsect1>
1126<title>Description</title>
1127<para>
1128   Converts a standard ATA taskfile to a Serial ATA
1129   FIS structure (Register - Host to Device).
1130</para>
1131</refsect1>
1132<refsect1>
1133<title>LOCKING</title>
1134<para>
1135   Inherited from caller.
1136</para>
1137</refsect1>
1138</refentry>
1139
1140<refentry id="API-ata-tf-from-fis">
1141<refentryinfo>
1142 <title>LINUX</title>
1143 <productname>Kernel Hackers Manual</productname>
1144 <date>July 2017</date>
1145</refentryinfo>
1146<refmeta>
1147 <refentrytitle><phrase>ata_tf_from_fis</phrase></refentrytitle>
1148 <manvolnum>9</manvolnum>
1149 <refmiscinfo class="version">4.1.27</refmiscinfo>
1150</refmeta>
1151<refnamediv>
1152 <refname>ata_tf_from_fis</refname>
1153 <refpurpose>
1154     Convert SATA FIS to ATA taskfile
1155 </refpurpose>
1156</refnamediv>
1157<refsynopsisdiv>
1158 <title>Synopsis</title>
1159  <funcsynopsis><funcprototype>
1160   <funcdef>void <function>ata_tf_from_fis </function></funcdef>
1161   <paramdef>const u8 * <parameter>fis</parameter></paramdef>
1162   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
1163  </funcprototype></funcsynopsis>
1164</refsynopsisdiv>
1165<refsect1>
1166 <title>Arguments</title>
1167 <variablelist>
1168  <varlistentry>
1169   <term><parameter>fis</parameter></term>
1170   <listitem>
1171    <para>
1172     Buffer from which data will be input
1173    </para>
1174   </listitem>
1175  </varlistentry>
1176  <varlistentry>
1177   <term><parameter>tf</parameter></term>
1178   <listitem>
1179    <para>
1180     Taskfile to output
1181    </para>
1182   </listitem>
1183  </varlistentry>
1184 </variablelist>
1185</refsect1>
1186<refsect1>
1187<title>Description</title>
1188<para>
1189   Converts a serial ATA FIS structure to a standard ATA taskfile.
1190</para>
1191</refsect1>
1192<refsect1>
1193<title>LOCKING</title>
1194<para>
1195   Inherited from caller.
1196</para>
1197</refsect1>
1198</refentry>
1199
1200<refentry id="API-ata-pack-xfermask">
1201<refentryinfo>
1202 <title>LINUX</title>
1203 <productname>Kernel Hackers Manual</productname>
1204 <date>July 2017</date>
1205</refentryinfo>
1206<refmeta>
1207 <refentrytitle><phrase>ata_pack_xfermask</phrase></refentrytitle>
1208 <manvolnum>9</manvolnum>
1209 <refmiscinfo class="version">4.1.27</refmiscinfo>
1210</refmeta>
1211<refnamediv>
1212 <refname>ata_pack_xfermask</refname>
1213 <refpurpose>
1214     Pack pio, mwdma and udma masks into xfer_mask
1215 </refpurpose>
1216</refnamediv>
1217<refsynopsisdiv>
1218 <title>Synopsis</title>
1219  <funcsynopsis><funcprototype>
1220   <funcdef>unsigned long <function>ata_pack_xfermask </function></funcdef>
1221   <paramdef>unsigned long <parameter>pio_mask</parameter></paramdef>
1222   <paramdef>unsigned long <parameter>mwdma_mask</parameter></paramdef>
1223   <paramdef>unsigned long <parameter>udma_mask</parameter></paramdef>
1224  </funcprototype></funcsynopsis>
1225</refsynopsisdiv>
1226<refsect1>
1227 <title>Arguments</title>
1228 <variablelist>
1229  <varlistentry>
1230   <term><parameter>pio_mask</parameter></term>
1231   <listitem>
1232    <para>
1233     pio_mask
1234    </para>
1235   </listitem>
1236  </varlistentry>
1237  <varlistentry>
1238   <term><parameter>mwdma_mask</parameter></term>
1239   <listitem>
1240    <para>
1241     mwdma_mask
1242    </para>
1243   </listitem>
1244  </varlistentry>
1245  <varlistentry>
1246   <term><parameter>udma_mask</parameter></term>
1247   <listitem>
1248    <para>
1249     udma_mask
1250    </para>
1251   </listitem>
1252  </varlistentry>
1253 </variablelist>
1254</refsect1>
1255<refsect1>
1256<title>Description</title>
1257<para>
1258   Pack <parameter>pio_mask</parameter>, <parameter>mwdma_mask</parameter> and <parameter>udma_mask</parameter> into a single
1259   unsigned int xfer_mask.
1260</para>
1261</refsect1>
1262<refsect1>
1263<title>LOCKING</title>
1264<para>
1265   None.
1266</para>
1267</refsect1>
1268<refsect1>
1269<title>RETURNS</title>
1270<para>
1271   Packed xfer_mask.
1272</para>
1273</refsect1>
1274</refentry>
1275
1276<refentry id="API-ata-unpack-xfermask">
1277<refentryinfo>
1278 <title>LINUX</title>
1279 <productname>Kernel Hackers Manual</productname>
1280 <date>July 2017</date>
1281</refentryinfo>
1282<refmeta>
1283 <refentrytitle><phrase>ata_unpack_xfermask</phrase></refentrytitle>
1284 <manvolnum>9</manvolnum>
1285 <refmiscinfo class="version">4.1.27</refmiscinfo>
1286</refmeta>
1287<refnamediv>
1288 <refname>ata_unpack_xfermask</refname>
1289 <refpurpose>
1290     Unpack xfer_mask into pio, mwdma and udma masks
1291 </refpurpose>
1292</refnamediv>
1293<refsynopsisdiv>
1294 <title>Synopsis</title>
1295  <funcsynopsis><funcprototype>
1296   <funcdef>void <function>ata_unpack_xfermask </function></funcdef>
1297   <paramdef>unsigned long <parameter>xfer_mask</parameter></paramdef>
1298   <paramdef>unsigned long * <parameter>pio_mask</parameter></paramdef>
1299   <paramdef>unsigned long * <parameter>mwdma_mask</parameter></paramdef>
1300   <paramdef>unsigned long * <parameter>udma_mask</parameter></paramdef>
1301  </funcprototype></funcsynopsis>
1302</refsynopsisdiv>
1303<refsect1>
1304 <title>Arguments</title>
1305 <variablelist>
1306  <varlistentry>
1307   <term><parameter>xfer_mask</parameter></term>
1308   <listitem>
1309    <para>
1310     xfer_mask to unpack
1311    </para>
1312   </listitem>
1313  </varlistentry>
1314  <varlistentry>
1315   <term><parameter>pio_mask</parameter></term>
1316   <listitem>
1317    <para>
1318     resulting pio_mask
1319    </para>
1320   </listitem>
1321  </varlistentry>
1322  <varlistentry>
1323   <term><parameter>mwdma_mask</parameter></term>
1324   <listitem>
1325    <para>
1326     resulting mwdma_mask
1327    </para>
1328   </listitem>
1329  </varlistentry>
1330  <varlistentry>
1331   <term><parameter>udma_mask</parameter></term>
1332   <listitem>
1333    <para>
1334     resulting udma_mask
1335    </para>
1336   </listitem>
1337  </varlistentry>
1338 </variablelist>
1339</refsect1>
1340<refsect1>
1341<title>Description</title>
1342<para>
1343   Unpack <parameter>xfer_mask</parameter> into <parameter>pio_mask</parameter>, <parameter>mwdma_mask</parameter> and <parameter>udma_mask</parameter>.
1344   Any NULL distination masks will be ignored.
1345</para>
1346</refsect1>
1347</refentry>
1348
1349<refentry id="API-ata-xfer-mask2mode">
1350<refentryinfo>
1351 <title>LINUX</title>
1352 <productname>Kernel Hackers Manual</productname>
1353 <date>July 2017</date>
1354</refentryinfo>
1355<refmeta>
1356 <refentrytitle><phrase>ata_xfer_mask2mode</phrase></refentrytitle>
1357 <manvolnum>9</manvolnum>
1358 <refmiscinfo class="version">4.1.27</refmiscinfo>
1359</refmeta>
1360<refnamediv>
1361 <refname>ata_xfer_mask2mode</refname>
1362 <refpurpose>
1363     Find matching XFER_* for the given xfer_mask
1364 </refpurpose>
1365</refnamediv>
1366<refsynopsisdiv>
1367 <title>Synopsis</title>
1368  <funcsynopsis><funcprototype>
1369   <funcdef>u8 <function>ata_xfer_mask2mode </function></funcdef>
1370   <paramdef>unsigned long <parameter>xfer_mask</parameter></paramdef>
1371  </funcprototype></funcsynopsis>
1372</refsynopsisdiv>
1373<refsect1>
1374 <title>Arguments</title>
1375 <variablelist>
1376  <varlistentry>
1377   <term><parameter>xfer_mask</parameter></term>
1378   <listitem>
1379    <para>
1380     xfer_mask of interest
1381    </para>
1382   </listitem>
1383  </varlistentry>
1384 </variablelist>
1385</refsect1>
1386<refsect1>
1387<title>Description</title>
1388<para>
1389   Return matching XFER_* value for <parameter>xfer_mask</parameter>.  Only the highest
1390   bit of <parameter>xfer_mask</parameter> is considered.
1391</para>
1392</refsect1>
1393<refsect1>
1394<title>LOCKING</title>
1395<para>
1396   None.
1397</para>
1398</refsect1>
1399<refsect1>
1400<title>RETURNS</title>
1401<para>
1402   Matching XFER_* value, 0xff if no match found.
1403</para>
1404</refsect1>
1405</refentry>
1406
1407<refentry id="API-ata-xfer-mode2mask">
1408<refentryinfo>
1409 <title>LINUX</title>
1410 <productname>Kernel Hackers Manual</productname>
1411 <date>July 2017</date>
1412</refentryinfo>
1413<refmeta>
1414 <refentrytitle><phrase>ata_xfer_mode2mask</phrase></refentrytitle>
1415 <manvolnum>9</manvolnum>
1416 <refmiscinfo class="version">4.1.27</refmiscinfo>
1417</refmeta>
1418<refnamediv>
1419 <refname>ata_xfer_mode2mask</refname>
1420 <refpurpose>
1421     Find matching xfer_mask for XFER_*
1422 </refpurpose>
1423</refnamediv>
1424<refsynopsisdiv>
1425 <title>Synopsis</title>
1426  <funcsynopsis><funcprototype>
1427   <funcdef>unsigned long <function>ata_xfer_mode2mask </function></funcdef>
1428   <paramdef>u8 <parameter>xfer_mode</parameter></paramdef>
1429  </funcprototype></funcsynopsis>
1430</refsynopsisdiv>
1431<refsect1>
1432 <title>Arguments</title>
1433 <variablelist>
1434  <varlistentry>
1435   <term><parameter>xfer_mode</parameter></term>
1436   <listitem>
1437    <para>
1438     XFER_* of interest
1439    </para>
1440   </listitem>
1441  </varlistentry>
1442 </variablelist>
1443</refsect1>
1444<refsect1>
1445<title>Description</title>
1446<para>
1447   Return matching xfer_mask for <parameter>xfer_mode</parameter>.
1448</para>
1449</refsect1>
1450<refsect1>
1451<title>LOCKING</title>
1452<para>
1453   None.
1454</para>
1455</refsect1>
1456<refsect1>
1457<title>RETURNS</title>
1458<para>
1459   Matching xfer_mask, 0 if no match found.
1460</para>
1461</refsect1>
1462</refentry>
1463
1464<refentry id="API-ata-xfer-mode2shift">
1465<refentryinfo>
1466 <title>LINUX</title>
1467 <productname>Kernel Hackers Manual</productname>
1468 <date>July 2017</date>
1469</refentryinfo>
1470<refmeta>
1471 <refentrytitle><phrase>ata_xfer_mode2shift</phrase></refentrytitle>
1472 <manvolnum>9</manvolnum>
1473 <refmiscinfo class="version">4.1.27</refmiscinfo>
1474</refmeta>
1475<refnamediv>
1476 <refname>ata_xfer_mode2shift</refname>
1477 <refpurpose>
1478     Find matching xfer_shift for XFER_*
1479 </refpurpose>
1480</refnamediv>
1481<refsynopsisdiv>
1482 <title>Synopsis</title>
1483  <funcsynopsis><funcprototype>
1484   <funcdef>int <function>ata_xfer_mode2shift </function></funcdef>
1485   <paramdef>unsigned long <parameter>xfer_mode</parameter></paramdef>
1486  </funcprototype></funcsynopsis>
1487</refsynopsisdiv>
1488<refsect1>
1489 <title>Arguments</title>
1490 <variablelist>
1491  <varlistentry>
1492   <term><parameter>xfer_mode</parameter></term>
1493   <listitem>
1494    <para>
1495     XFER_* of interest
1496    </para>
1497   </listitem>
1498  </varlistentry>
1499 </variablelist>
1500</refsect1>
1501<refsect1>
1502<title>Description</title>
1503<para>
1504   Return matching xfer_shift for <parameter>xfer_mode</parameter>.
1505</para>
1506</refsect1>
1507<refsect1>
1508<title>LOCKING</title>
1509<para>
1510   None.
1511</para>
1512</refsect1>
1513<refsect1>
1514<title>RETURNS</title>
1515<para>
1516   Matching xfer_shift, -1 if no match found.
1517</para>
1518</refsect1>
1519</refentry>
1520
1521<refentry id="API-ata-mode-string">
1522<refentryinfo>
1523 <title>LINUX</title>
1524 <productname>Kernel Hackers Manual</productname>
1525 <date>July 2017</date>
1526</refentryinfo>
1527<refmeta>
1528 <refentrytitle><phrase>ata_mode_string</phrase></refentrytitle>
1529 <manvolnum>9</manvolnum>
1530 <refmiscinfo class="version">4.1.27</refmiscinfo>
1531</refmeta>
1532<refnamediv>
1533 <refname>ata_mode_string</refname>
1534 <refpurpose>
1535     convert xfer_mask to string
1536 </refpurpose>
1537</refnamediv>
1538<refsynopsisdiv>
1539 <title>Synopsis</title>
1540  <funcsynopsis><funcprototype>
1541   <funcdef>const char * <function>ata_mode_string </function></funcdef>
1542   <paramdef>unsigned long <parameter>xfer_mask</parameter></paramdef>
1543  </funcprototype></funcsynopsis>
1544</refsynopsisdiv>
1545<refsect1>
1546 <title>Arguments</title>
1547 <variablelist>
1548  <varlistentry>
1549   <term><parameter>xfer_mask</parameter></term>
1550   <listitem>
1551    <para>
1552     mask of bits supported; only highest bit counts.
1553    </para>
1554   </listitem>
1555  </varlistentry>
1556 </variablelist>
1557</refsect1>
1558<refsect1>
1559<title>Description</title>
1560<para>
1561   Determine string which represents the highest speed
1562   (highest bit in <parameter>modemask</parameter>).
1563</para>
1564</refsect1>
1565<refsect1>
1566<title>LOCKING</title>
1567<para>
1568   None.
1569</para>
1570</refsect1>
1571<refsect1>
1572<title>RETURNS</title>
1573<para>
1574   Constant C string representing highest speed listed in
1575   <parameter>mode_mask</parameter>, or the constant C string <quote>&lt;n/a&gt;</quote>.
1576</para>
1577</refsect1>
1578</refentry>
1579
1580<refentry id="API-ata-dev-classify">
1581<refentryinfo>
1582 <title>LINUX</title>
1583 <productname>Kernel Hackers Manual</productname>
1584 <date>July 2017</date>
1585</refentryinfo>
1586<refmeta>
1587 <refentrytitle><phrase>ata_dev_classify</phrase></refentrytitle>
1588 <manvolnum>9</manvolnum>
1589 <refmiscinfo class="version">4.1.27</refmiscinfo>
1590</refmeta>
1591<refnamediv>
1592 <refname>ata_dev_classify</refname>
1593 <refpurpose>
1594     determine device type based on ATA-spec signature
1595 </refpurpose>
1596</refnamediv>
1597<refsynopsisdiv>
1598 <title>Synopsis</title>
1599  <funcsynopsis><funcprototype>
1600   <funcdef>unsigned int <function>ata_dev_classify </function></funcdef>
1601   <paramdef>const struct ata_taskfile * <parameter>tf</parameter></paramdef>
1602  </funcprototype></funcsynopsis>
1603</refsynopsisdiv>
1604<refsect1>
1605 <title>Arguments</title>
1606 <variablelist>
1607  <varlistentry>
1608   <term><parameter>tf</parameter></term>
1609   <listitem>
1610    <para>
1611     ATA taskfile register set for device to be identified
1612    </para>
1613   </listitem>
1614  </varlistentry>
1615 </variablelist>
1616</refsect1>
1617<refsect1>
1618<title>Description</title>
1619<para>
1620   Determine from taskfile register contents whether a device is
1621   ATA or ATAPI, as per <quote>Signature and persistence</quote> section
1622   of ATA/PI spec (volume 1, sect 5.14).
1623</para>
1624</refsect1>
1625<refsect1>
1626<title>LOCKING</title>
1627<para>
1628   None.
1629</para>
1630</refsect1>
1631<refsect1>
1632<title>RETURNS</title>
1633<para>
1634   Device type, <constant>ATA_DEV_ATA</constant>, <constant>ATA_DEV_ATAPI</constant>, <constant>ATA_DEV_PMP</constant>,
1635   <constant>ATA_DEV_ZAC</constant>, or <constant>ATA_DEV_UNKNOWN</constant> the event of failure.
1636</para>
1637</refsect1>
1638</refentry>
1639
1640<refentry id="API-ata-id-string">
1641<refentryinfo>
1642 <title>LINUX</title>
1643 <productname>Kernel Hackers Manual</productname>
1644 <date>July 2017</date>
1645</refentryinfo>
1646<refmeta>
1647 <refentrytitle><phrase>ata_id_string</phrase></refentrytitle>
1648 <manvolnum>9</manvolnum>
1649 <refmiscinfo class="version">4.1.27</refmiscinfo>
1650</refmeta>
1651<refnamediv>
1652 <refname>ata_id_string</refname>
1653 <refpurpose>
1654     Convert IDENTIFY DEVICE page into string
1655 </refpurpose>
1656</refnamediv>
1657<refsynopsisdiv>
1658 <title>Synopsis</title>
1659  <funcsynopsis><funcprototype>
1660   <funcdef>void <function>ata_id_string </function></funcdef>
1661   <paramdef>const u16 * <parameter>id</parameter></paramdef>
1662   <paramdef>unsigned char * <parameter>s</parameter></paramdef>
1663   <paramdef>unsigned int <parameter>ofs</parameter></paramdef>
1664   <paramdef>unsigned int <parameter>len</parameter></paramdef>
1665  </funcprototype></funcsynopsis>
1666</refsynopsisdiv>
1667<refsect1>
1668 <title>Arguments</title>
1669 <variablelist>
1670  <varlistentry>
1671   <term><parameter>id</parameter></term>
1672   <listitem>
1673    <para>
1674     IDENTIFY DEVICE results we will examine
1675    </para>
1676   </listitem>
1677  </varlistentry>
1678  <varlistentry>
1679   <term><parameter>s</parameter></term>
1680   <listitem>
1681    <para>
1682     string into which data is output
1683    </para>
1684   </listitem>
1685  </varlistentry>
1686  <varlistentry>
1687   <term><parameter>ofs</parameter></term>
1688   <listitem>
1689    <para>
1690     offset into identify device page
1691    </para>
1692   </listitem>
1693  </varlistentry>
1694  <varlistentry>
1695   <term><parameter>len</parameter></term>
1696   <listitem>
1697    <para>
1698     length of string to return. must be an even number.
1699    </para>
1700   </listitem>
1701  </varlistentry>
1702 </variablelist>
1703</refsect1>
1704<refsect1>
1705<title>Description</title>
1706<para>
1707   The strings in the IDENTIFY DEVICE page are broken up into
1708   16-bit chunks.  Run through the string, and output each
1709   8-bit chunk linearly, regardless of platform.
1710</para>
1711</refsect1>
1712<refsect1>
1713<title>LOCKING</title>
1714<para>
1715   caller.
1716</para>
1717</refsect1>
1718</refentry>
1719
1720<refentry id="API-ata-id-c-string">
1721<refentryinfo>
1722 <title>LINUX</title>
1723 <productname>Kernel Hackers Manual</productname>
1724 <date>July 2017</date>
1725</refentryinfo>
1726<refmeta>
1727 <refentrytitle><phrase>ata_id_c_string</phrase></refentrytitle>
1728 <manvolnum>9</manvolnum>
1729 <refmiscinfo class="version">4.1.27</refmiscinfo>
1730</refmeta>
1731<refnamediv>
1732 <refname>ata_id_c_string</refname>
1733 <refpurpose>
1734     Convert IDENTIFY DEVICE page into C string
1735 </refpurpose>
1736</refnamediv>
1737<refsynopsisdiv>
1738 <title>Synopsis</title>
1739  <funcsynopsis><funcprototype>
1740   <funcdef>void <function>ata_id_c_string </function></funcdef>
1741   <paramdef>const u16 * <parameter>id</parameter></paramdef>
1742   <paramdef>unsigned char * <parameter>s</parameter></paramdef>
1743   <paramdef>unsigned int <parameter>ofs</parameter></paramdef>
1744   <paramdef>unsigned int <parameter>len</parameter></paramdef>
1745  </funcprototype></funcsynopsis>
1746</refsynopsisdiv>
1747<refsect1>
1748 <title>Arguments</title>
1749 <variablelist>
1750  <varlistentry>
1751   <term><parameter>id</parameter></term>
1752   <listitem>
1753    <para>
1754     IDENTIFY DEVICE results we will examine
1755    </para>
1756   </listitem>
1757  </varlistentry>
1758  <varlistentry>
1759   <term><parameter>s</parameter></term>
1760   <listitem>
1761    <para>
1762     string into which data is output
1763    </para>
1764   </listitem>
1765  </varlistentry>
1766  <varlistentry>
1767   <term><parameter>ofs</parameter></term>
1768   <listitem>
1769    <para>
1770     offset into identify device page
1771    </para>
1772   </listitem>
1773  </varlistentry>
1774  <varlistentry>
1775   <term><parameter>len</parameter></term>
1776   <listitem>
1777    <para>
1778     length of string to return. must be an odd number.
1779    </para>
1780   </listitem>
1781  </varlistentry>
1782 </variablelist>
1783</refsect1>
1784<refsect1>
1785<title>Description</title>
1786<para>
1787   This function is identical to ata_id_string except that it
1788   trims trailing spaces and terminates the resulting string with
1789   null.  <parameter>len</parameter> must be actual maximum length (even number) + 1.
1790</para>
1791</refsect1>
1792<refsect1>
1793<title>LOCKING</title>
1794<para>
1795   caller.
1796</para>
1797</refsect1>
1798</refentry>
1799
1800<refentry id="API-ata-id-xfermask">
1801<refentryinfo>
1802 <title>LINUX</title>
1803 <productname>Kernel Hackers Manual</productname>
1804 <date>July 2017</date>
1805</refentryinfo>
1806<refmeta>
1807 <refentrytitle><phrase>ata_id_xfermask</phrase></refentrytitle>
1808 <manvolnum>9</manvolnum>
1809 <refmiscinfo class="version">4.1.27</refmiscinfo>
1810</refmeta>
1811<refnamediv>
1812 <refname>ata_id_xfermask</refname>
1813 <refpurpose>
1814     Compute xfermask from the given IDENTIFY data
1815 </refpurpose>
1816</refnamediv>
1817<refsynopsisdiv>
1818 <title>Synopsis</title>
1819  <funcsynopsis><funcprototype>
1820   <funcdef>unsigned long <function>ata_id_xfermask </function></funcdef>
1821   <paramdef>const u16 * <parameter>id</parameter></paramdef>
1822  </funcprototype></funcsynopsis>
1823</refsynopsisdiv>
1824<refsect1>
1825 <title>Arguments</title>
1826 <variablelist>
1827  <varlistentry>
1828   <term><parameter>id</parameter></term>
1829   <listitem>
1830    <para>
1831     IDENTIFY data to compute xfer mask from
1832    </para>
1833   </listitem>
1834  </varlistentry>
1835 </variablelist>
1836</refsect1>
1837<refsect1>
1838<title>Description</title>
1839<para>
1840   Compute the xfermask for this device. This is not as trivial
1841   as it seems if we must consider early devices correctly.
1842</para>
1843</refsect1>
1844<refsect1>
1845<title>FIXME</title>
1846<para>
1847   pre IDE drive timing (do we care ?).
1848</para>
1849</refsect1>
1850<refsect1>
1851<title>LOCKING</title>
1852<para>
1853   None.
1854</para>
1855</refsect1>
1856<refsect1>
1857<title>RETURNS</title>
1858<para>
1859   Computed xfermask
1860</para>
1861</refsect1>
1862</refentry>
1863
1864<refentry id="API-ata-pio-need-iordy">
1865<refentryinfo>
1866 <title>LINUX</title>
1867 <productname>Kernel Hackers Manual</productname>
1868 <date>July 2017</date>
1869</refentryinfo>
1870<refmeta>
1871 <refentrytitle><phrase>ata_pio_need_iordy</phrase></refentrytitle>
1872 <manvolnum>9</manvolnum>
1873 <refmiscinfo class="version">4.1.27</refmiscinfo>
1874</refmeta>
1875<refnamediv>
1876 <refname>ata_pio_need_iordy</refname>
1877 <refpurpose>
1878     check if iordy needed
1879 </refpurpose>
1880</refnamediv>
1881<refsynopsisdiv>
1882 <title>Synopsis</title>
1883  <funcsynopsis><funcprototype>
1884   <funcdef>unsigned int <function>ata_pio_need_iordy </function></funcdef>
1885   <paramdef>const struct ata_device * <parameter>adev</parameter></paramdef>
1886  </funcprototype></funcsynopsis>
1887</refsynopsisdiv>
1888<refsect1>
1889 <title>Arguments</title>
1890 <variablelist>
1891  <varlistentry>
1892   <term><parameter>adev</parameter></term>
1893   <listitem>
1894    <para>
1895     ATA device
1896    </para>
1897   </listitem>
1898  </varlistentry>
1899 </variablelist>
1900</refsect1>
1901<refsect1>
1902<title>Description</title>
1903<para>
1904   Check if the current speed of the device requires IORDY. Used
1905   by various controllers for chip configuration.
1906</para>
1907</refsect1>
1908</refentry>
1909
1910<refentry id="API-ata-do-dev-read-id">
1911<refentryinfo>
1912 <title>LINUX</title>
1913 <productname>Kernel Hackers Manual</productname>
1914 <date>July 2017</date>
1915</refentryinfo>
1916<refmeta>
1917 <refentrytitle><phrase>ata_do_dev_read_id</phrase></refentrytitle>
1918 <manvolnum>9</manvolnum>
1919 <refmiscinfo class="version">4.1.27</refmiscinfo>
1920</refmeta>
1921<refnamediv>
1922 <refname>ata_do_dev_read_id</refname>
1923 <refpurpose>
1924     default ID read method
1925 </refpurpose>
1926</refnamediv>
1927<refsynopsisdiv>
1928 <title>Synopsis</title>
1929  <funcsynopsis><funcprototype>
1930   <funcdef>unsigned int <function>ata_do_dev_read_id </function></funcdef>
1931   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
1932   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
1933   <paramdef>u16 * <parameter>id</parameter></paramdef>
1934  </funcprototype></funcsynopsis>
1935</refsynopsisdiv>
1936<refsect1>
1937 <title>Arguments</title>
1938 <variablelist>
1939  <varlistentry>
1940   <term><parameter>dev</parameter></term>
1941   <listitem>
1942    <para>
1943     device
1944    </para>
1945   </listitem>
1946  </varlistentry>
1947  <varlistentry>
1948   <term><parameter>tf</parameter></term>
1949   <listitem>
1950    <para>
1951     proposed taskfile
1952    </para>
1953   </listitem>
1954  </varlistentry>
1955  <varlistentry>
1956   <term><parameter>id</parameter></term>
1957   <listitem>
1958    <para>
1959     data buffer
1960    </para>
1961   </listitem>
1962  </varlistentry>
1963 </variablelist>
1964</refsect1>
1965<refsect1>
1966<title>Description</title>
1967<para>
1968   Issue the identify taskfile and hand back the buffer containing
1969   identify data. For some RAID controllers and for pre ATA devices
1970   this function is wrapped or replaced by the driver
1971</para>
1972</refsect1>
1973</refentry>
1974
1975<refentry id="API-ata-cable-40wire">
1976<refentryinfo>
1977 <title>LINUX</title>
1978 <productname>Kernel Hackers Manual</productname>
1979 <date>July 2017</date>
1980</refentryinfo>
1981<refmeta>
1982 <refentrytitle><phrase>ata_cable_40wire</phrase></refentrytitle>
1983 <manvolnum>9</manvolnum>
1984 <refmiscinfo class="version">4.1.27</refmiscinfo>
1985</refmeta>
1986<refnamediv>
1987 <refname>ata_cable_40wire</refname>
1988 <refpurpose>
1989     return 40 wire cable type
1990 </refpurpose>
1991</refnamediv>
1992<refsynopsisdiv>
1993 <title>Synopsis</title>
1994  <funcsynopsis><funcprototype>
1995   <funcdef>int <function>ata_cable_40wire </function></funcdef>
1996   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
1997  </funcprototype></funcsynopsis>
1998</refsynopsisdiv>
1999<refsect1>
2000 <title>Arguments</title>
2001 <variablelist>
2002  <varlistentry>
2003   <term><parameter>ap</parameter></term>
2004   <listitem>
2005    <para>
2006     port
2007    </para>
2008   </listitem>
2009  </varlistentry>
2010 </variablelist>
2011</refsect1>
2012<refsect1>
2013<title>Description</title>
2014<para>
2015   Helper method for drivers which want to hardwire 40 wire cable
2016   detection.
2017</para>
2018</refsect1>
2019</refentry>
2020
2021<refentry id="API-ata-cable-80wire">
2022<refentryinfo>
2023 <title>LINUX</title>
2024 <productname>Kernel Hackers Manual</productname>
2025 <date>July 2017</date>
2026</refentryinfo>
2027<refmeta>
2028 <refentrytitle><phrase>ata_cable_80wire</phrase></refentrytitle>
2029 <manvolnum>9</manvolnum>
2030 <refmiscinfo class="version">4.1.27</refmiscinfo>
2031</refmeta>
2032<refnamediv>
2033 <refname>ata_cable_80wire</refname>
2034 <refpurpose>
2035     return 80 wire cable type
2036 </refpurpose>
2037</refnamediv>
2038<refsynopsisdiv>
2039 <title>Synopsis</title>
2040  <funcsynopsis><funcprototype>
2041   <funcdef>int <function>ata_cable_80wire </function></funcdef>
2042   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
2043  </funcprototype></funcsynopsis>
2044</refsynopsisdiv>
2045<refsect1>
2046 <title>Arguments</title>
2047 <variablelist>
2048  <varlistentry>
2049   <term><parameter>ap</parameter></term>
2050   <listitem>
2051    <para>
2052     port
2053    </para>
2054   </listitem>
2055  </varlistentry>
2056 </variablelist>
2057</refsect1>
2058<refsect1>
2059<title>Description</title>
2060<para>
2061   Helper method for drivers which want to hardwire 80 wire cable
2062   detection.
2063</para>
2064</refsect1>
2065</refentry>
2066
2067<refentry id="API-ata-cable-unknown">
2068<refentryinfo>
2069 <title>LINUX</title>
2070 <productname>Kernel Hackers Manual</productname>
2071 <date>July 2017</date>
2072</refentryinfo>
2073<refmeta>
2074 <refentrytitle><phrase>ata_cable_unknown</phrase></refentrytitle>
2075 <manvolnum>9</manvolnum>
2076 <refmiscinfo class="version">4.1.27</refmiscinfo>
2077</refmeta>
2078<refnamediv>
2079 <refname>ata_cable_unknown</refname>
2080 <refpurpose>
2081     return unknown PATA cable.
2082 </refpurpose>
2083</refnamediv>
2084<refsynopsisdiv>
2085 <title>Synopsis</title>
2086  <funcsynopsis><funcprototype>
2087   <funcdef>int <function>ata_cable_unknown </function></funcdef>
2088   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
2089  </funcprototype></funcsynopsis>
2090</refsynopsisdiv>
2091<refsect1>
2092 <title>Arguments</title>
2093 <variablelist>
2094  <varlistentry>
2095   <term><parameter>ap</parameter></term>
2096   <listitem>
2097    <para>
2098     port
2099    </para>
2100   </listitem>
2101  </varlistentry>
2102 </variablelist>
2103</refsect1>
2104<refsect1>
2105<title>Description</title>
2106<para>
2107   Helper method for drivers which have no PATA cable detection.
2108</para>
2109</refsect1>
2110</refentry>
2111
2112<refentry id="API-ata-cable-ignore">
2113<refentryinfo>
2114 <title>LINUX</title>
2115 <productname>Kernel Hackers Manual</productname>
2116 <date>July 2017</date>
2117</refentryinfo>
2118<refmeta>
2119 <refentrytitle><phrase>ata_cable_ignore</phrase></refentrytitle>
2120 <manvolnum>9</manvolnum>
2121 <refmiscinfo class="version">4.1.27</refmiscinfo>
2122</refmeta>
2123<refnamediv>
2124 <refname>ata_cable_ignore</refname>
2125 <refpurpose>
2126     return ignored PATA cable.
2127 </refpurpose>
2128</refnamediv>
2129<refsynopsisdiv>
2130 <title>Synopsis</title>
2131  <funcsynopsis><funcprototype>
2132   <funcdef>int <function>ata_cable_ignore </function></funcdef>
2133   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
2134  </funcprototype></funcsynopsis>
2135</refsynopsisdiv>
2136<refsect1>
2137 <title>Arguments</title>
2138 <variablelist>
2139  <varlistentry>
2140   <term><parameter>ap</parameter></term>
2141   <listitem>
2142    <para>
2143     port
2144    </para>
2145   </listitem>
2146  </varlistentry>
2147 </variablelist>
2148</refsect1>
2149<refsect1>
2150<title>Description</title>
2151<para>
2152   Helper method for drivers which don't use cable type to limit
2153   transfer mode.
2154</para>
2155</refsect1>
2156</refentry>
2157
2158<refentry id="API-ata-cable-sata">
2159<refentryinfo>
2160 <title>LINUX</title>
2161 <productname>Kernel Hackers Manual</productname>
2162 <date>July 2017</date>
2163</refentryinfo>
2164<refmeta>
2165 <refentrytitle><phrase>ata_cable_sata</phrase></refentrytitle>
2166 <manvolnum>9</manvolnum>
2167 <refmiscinfo class="version">4.1.27</refmiscinfo>
2168</refmeta>
2169<refnamediv>
2170 <refname>ata_cable_sata</refname>
2171 <refpurpose>
2172     return SATA cable type
2173 </refpurpose>
2174</refnamediv>
2175<refsynopsisdiv>
2176 <title>Synopsis</title>
2177  <funcsynopsis><funcprototype>
2178   <funcdef>int <function>ata_cable_sata </function></funcdef>
2179   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
2180  </funcprototype></funcsynopsis>
2181</refsynopsisdiv>
2182<refsect1>
2183 <title>Arguments</title>
2184 <variablelist>
2185  <varlistentry>
2186   <term><parameter>ap</parameter></term>
2187   <listitem>
2188    <para>
2189     port
2190    </para>
2191   </listitem>
2192  </varlistentry>
2193 </variablelist>
2194</refsect1>
2195<refsect1>
2196<title>Description</title>
2197<para>
2198   Helper method for drivers which have SATA cables
2199</para>
2200</refsect1>
2201</refentry>
2202
2203<refentry id="API-ata-dev-pair">
2204<refentryinfo>
2205 <title>LINUX</title>
2206 <productname>Kernel Hackers Manual</productname>
2207 <date>July 2017</date>
2208</refentryinfo>
2209<refmeta>
2210 <refentrytitle><phrase>ata_dev_pair</phrase></refentrytitle>
2211 <manvolnum>9</manvolnum>
2212 <refmiscinfo class="version">4.1.27</refmiscinfo>
2213</refmeta>
2214<refnamediv>
2215 <refname>ata_dev_pair</refname>
2216 <refpurpose>
2217     return other device on cable
2218 </refpurpose>
2219</refnamediv>
2220<refsynopsisdiv>
2221 <title>Synopsis</title>
2222  <funcsynopsis><funcprototype>
2223   <funcdef>struct ata_device * <function>ata_dev_pair </function></funcdef>
2224   <paramdef>struct ata_device * <parameter>adev</parameter></paramdef>
2225  </funcprototype></funcsynopsis>
2226</refsynopsisdiv>
2227<refsect1>
2228 <title>Arguments</title>
2229 <variablelist>
2230  <varlistentry>
2231   <term><parameter>adev</parameter></term>
2232   <listitem>
2233    <para>
2234     device
2235    </para>
2236   </listitem>
2237  </varlistentry>
2238 </variablelist>
2239</refsect1>
2240<refsect1>
2241<title>Description</title>
2242<para>
2243   Obtain the other device on the same cable, or if none is
2244   present NULL is returned
2245</para>
2246</refsect1>
2247</refentry>
2248
2249<refentry id="API-sata-set-spd">
2250<refentryinfo>
2251 <title>LINUX</title>
2252 <productname>Kernel Hackers Manual</productname>
2253 <date>July 2017</date>
2254</refentryinfo>
2255<refmeta>
2256 <refentrytitle><phrase>sata_set_spd</phrase></refentrytitle>
2257 <manvolnum>9</manvolnum>
2258 <refmiscinfo class="version">4.1.27</refmiscinfo>
2259</refmeta>
2260<refnamediv>
2261 <refname>sata_set_spd</refname>
2262 <refpurpose>
2263     set SATA spd according to spd limit
2264 </refpurpose>
2265</refnamediv>
2266<refsynopsisdiv>
2267 <title>Synopsis</title>
2268  <funcsynopsis><funcprototype>
2269   <funcdef>int <function>sata_set_spd </function></funcdef>
2270   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2271  </funcprototype></funcsynopsis>
2272</refsynopsisdiv>
2273<refsect1>
2274 <title>Arguments</title>
2275 <variablelist>
2276  <varlistentry>
2277   <term><parameter>link</parameter></term>
2278   <listitem>
2279    <para>
2280     Link to set SATA spd for
2281    </para>
2282   </listitem>
2283  </varlistentry>
2284 </variablelist>
2285</refsect1>
2286<refsect1>
2287<title>Description</title>
2288<para>
2289   Set SATA spd of <parameter>link</parameter> according to sata_spd_limit.
2290</para>
2291</refsect1>
2292<refsect1>
2293<title>LOCKING</title>
2294<para>
2295   Inherited from caller.
2296</para>
2297</refsect1>
2298<refsect1>
2299<title>RETURNS</title>
2300<para>
2301   0 if spd doesn't need to be changed, 1 if spd has been
2302   changed.  Negative errno if SCR registers are inaccessible.
2303</para>
2304</refsect1>
2305</refentry>
2306
2307<refentry id="API-ata-timing-cycle2mode">
2308<refentryinfo>
2309 <title>LINUX</title>
2310 <productname>Kernel Hackers Manual</productname>
2311 <date>July 2017</date>
2312</refentryinfo>
2313<refmeta>
2314 <refentrytitle><phrase>ata_timing_cycle2mode</phrase></refentrytitle>
2315 <manvolnum>9</manvolnum>
2316 <refmiscinfo class="version">4.1.27</refmiscinfo>
2317</refmeta>
2318<refnamediv>
2319 <refname>ata_timing_cycle2mode</refname>
2320 <refpurpose>
2321     find xfer mode for the specified cycle duration
2322 </refpurpose>
2323</refnamediv>
2324<refsynopsisdiv>
2325 <title>Synopsis</title>
2326  <funcsynopsis><funcprototype>
2327   <funcdef>u8 <function>ata_timing_cycle2mode </function></funcdef>
2328   <paramdef>unsigned int <parameter>xfer_shift</parameter></paramdef>
2329   <paramdef>int <parameter>cycle</parameter></paramdef>
2330  </funcprototype></funcsynopsis>
2331</refsynopsisdiv>
2332<refsect1>
2333 <title>Arguments</title>
2334 <variablelist>
2335  <varlistentry>
2336   <term><parameter>xfer_shift</parameter></term>
2337   <listitem>
2338    <para>
2339     ATA_SHIFT_* value for transfer type to examine.
2340    </para>
2341   </listitem>
2342  </varlistentry>
2343  <varlistentry>
2344   <term><parameter>cycle</parameter></term>
2345   <listitem>
2346    <para>
2347     cycle duration in ns
2348    </para>
2349   </listitem>
2350  </varlistentry>
2351 </variablelist>
2352</refsect1>
2353<refsect1>
2354<title>Description</title>
2355<para>
2356   Return matching xfer mode for <parameter>cycle</parameter>.  The returned mode is of
2357   the transfer type specified by <parameter>xfer_shift</parameter>.  If <parameter>cycle</parameter> is too
2358   slow for <parameter>xfer_shift</parameter>, 0xff is returned.  If <parameter>cycle</parameter> is faster
2359   than the fastest known mode, the fasted mode is returned.
2360</para>
2361</refsect1>
2362<refsect1>
2363<title>LOCKING</title>
2364<para>
2365   None.
2366</para>
2367</refsect1>
2368<refsect1>
2369<title>RETURNS</title>
2370<para>
2371   Matching xfer_mode, 0xff if no match found.
2372</para>
2373</refsect1>
2374</refentry>
2375
2376<refentry id="API-ata-do-set-mode">
2377<refentryinfo>
2378 <title>LINUX</title>
2379 <productname>Kernel Hackers Manual</productname>
2380 <date>July 2017</date>
2381</refentryinfo>
2382<refmeta>
2383 <refentrytitle><phrase>ata_do_set_mode</phrase></refentrytitle>
2384 <manvolnum>9</manvolnum>
2385 <refmiscinfo class="version">4.1.27</refmiscinfo>
2386</refmeta>
2387<refnamediv>
2388 <refname>ata_do_set_mode</refname>
2389 <refpurpose>
2390     Program timings and issue SET FEATURES - XFER
2391 </refpurpose>
2392</refnamediv>
2393<refsynopsisdiv>
2394 <title>Synopsis</title>
2395  <funcsynopsis><funcprototype>
2396   <funcdef>int <function>ata_do_set_mode </function></funcdef>
2397   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2398   <paramdef>struct ata_device ** <parameter>r_failed_dev</parameter></paramdef>
2399  </funcprototype></funcsynopsis>
2400</refsynopsisdiv>
2401<refsect1>
2402 <title>Arguments</title>
2403 <variablelist>
2404  <varlistentry>
2405   <term><parameter>link</parameter></term>
2406   <listitem>
2407    <para>
2408     link on which timings will be programmed
2409    </para>
2410   </listitem>
2411  </varlistentry>
2412  <varlistentry>
2413   <term><parameter>r_failed_dev</parameter></term>
2414   <listitem>
2415    <para>
2416     out parameter for failed device
2417    </para>
2418   </listitem>
2419  </varlistentry>
2420 </variablelist>
2421</refsect1>
2422<refsect1>
2423<title>Description</title>
2424<para>
2425   Standard implementation of the function used to tune and set
2426   ATA device disk transfer mode (PIO3, UDMA6, etc.).  If
2427   <function>ata_dev_set_mode</function> fails, pointer to the failing device is
2428   returned in <parameter>r_failed_dev</parameter>.
2429</para>
2430</refsect1>
2431<refsect1>
2432<title>LOCKING</title>
2433<para>
2434   PCI/etc. bus probe sem.
2435</para>
2436</refsect1>
2437<refsect1>
2438<title>RETURNS</title>
2439<para>
2440   0 on success, negative errno otherwise
2441</para>
2442</refsect1>
2443</refentry>
2444
2445<refentry id="API-ata-wait-after-reset">
2446<refentryinfo>
2447 <title>LINUX</title>
2448 <productname>Kernel Hackers Manual</productname>
2449 <date>July 2017</date>
2450</refentryinfo>
2451<refmeta>
2452 <refentrytitle><phrase>ata_wait_after_reset</phrase></refentrytitle>
2453 <manvolnum>9</manvolnum>
2454 <refmiscinfo class="version">4.1.27</refmiscinfo>
2455</refmeta>
2456<refnamediv>
2457 <refname>ata_wait_after_reset</refname>
2458 <refpurpose>
2459     wait for link to become ready after reset
2460 </refpurpose>
2461</refnamediv>
2462<refsynopsisdiv>
2463 <title>Synopsis</title>
2464  <funcsynopsis><funcprototype>
2465   <funcdef>int <function>ata_wait_after_reset </function></funcdef>
2466   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2467   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
2468   <paramdef>int (*<parameter>check_ready</parameter>)
2469     <funcparams>struct ata_link *link</funcparams></paramdef>
2470  </funcprototype></funcsynopsis>
2471</refsynopsisdiv>
2472<refsect1>
2473 <title>Arguments</title>
2474 <variablelist>
2475  <varlistentry>
2476   <term><parameter>link</parameter></term>
2477   <listitem>
2478    <para>
2479     link to be waited on
2480    </para>
2481   </listitem>
2482  </varlistentry>
2483  <varlistentry>
2484   <term><parameter>deadline</parameter></term>
2485   <listitem>
2486    <para>
2487     deadline jiffies for the operation
2488    </para>
2489   </listitem>
2490  </varlistentry>
2491  <varlistentry>
2492   <term><parameter>check_ready</parameter></term>
2493   <listitem>
2494    <para>
2495     callback to check link readiness
2496    </para>
2497   </listitem>
2498  </varlistentry>
2499 </variablelist>
2500</refsect1>
2501<refsect1>
2502<title>Description</title>
2503<para>
2504   Wait for <parameter>link</parameter> to become ready after reset.
2505</para>
2506</refsect1>
2507<refsect1>
2508<title>LOCKING</title>
2509<para>
2510   EH context.
2511</para>
2512</refsect1>
2513<refsect1>
2514<title>RETURNS</title>
2515<para>
2516   0 if <parameter>linke</parameter> is ready before <parameter>deadline</parameter>; otherwise, -errno.
2517</para>
2518</refsect1>
2519</refentry>
2520
2521<refentry id="API-sata-link-debounce">
2522<refentryinfo>
2523 <title>LINUX</title>
2524 <productname>Kernel Hackers Manual</productname>
2525 <date>July 2017</date>
2526</refentryinfo>
2527<refmeta>
2528 <refentrytitle><phrase>sata_link_debounce</phrase></refentrytitle>
2529 <manvolnum>9</manvolnum>
2530 <refmiscinfo class="version">4.1.27</refmiscinfo>
2531</refmeta>
2532<refnamediv>
2533 <refname>sata_link_debounce</refname>
2534 <refpurpose>
2535     debounce SATA phy status
2536 </refpurpose>
2537</refnamediv>
2538<refsynopsisdiv>
2539 <title>Synopsis</title>
2540  <funcsynopsis><funcprototype>
2541   <funcdef>int <function>sata_link_debounce </function></funcdef>
2542   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2543   <paramdef>const unsigned long * <parameter>params</parameter></paramdef>
2544   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
2545  </funcprototype></funcsynopsis>
2546</refsynopsisdiv>
2547<refsect1>
2548 <title>Arguments</title>
2549 <variablelist>
2550  <varlistentry>
2551   <term><parameter>link</parameter></term>
2552   <listitem>
2553    <para>
2554     ATA link to debounce SATA phy status for
2555    </para>
2556   </listitem>
2557  </varlistentry>
2558  <varlistentry>
2559   <term><parameter>params</parameter></term>
2560   <listitem>
2561    <para>
2562     timing parameters { interval, duratinon, timeout } in msec
2563    </para>
2564   </listitem>
2565  </varlistentry>
2566  <varlistentry>
2567   <term><parameter>deadline</parameter></term>
2568   <listitem>
2569    <para>
2570     deadline jiffies for the operation
2571    </para>
2572   </listitem>
2573  </varlistentry>
2574 </variablelist>
2575</refsect1>
2576<refsect1>
2577<title>Description</title>
2578<para>
2579   Make sure SStatus of <parameter>link</parameter> reaches stable state, determined by
2580   holding the same value where DET is not 1 for <parameter>duration</parameter> polled
2581   every <parameter>interval</parameter>, before <parameter>timeout</parameter>.  Timeout constraints the
2582   beginning of the stable state.  Because DET gets stuck at 1 on
2583   some controllers after hot unplugging, this functions waits
2584   until timeout then returns 0 if DET is stable at 1.
2585   </para><para>
2586
2587   <parameter>timeout</parameter> is further limited by <parameter>deadline</parameter>.  The sooner of the
2588   two is used.
2589</para>
2590</refsect1>
2591<refsect1>
2592<title>LOCKING</title>
2593<para>
2594   Kernel thread context (may sleep)
2595</para>
2596</refsect1>
2597<refsect1>
2598<title>RETURNS</title>
2599<para>
2600   0 on success, -errno on failure.
2601</para>
2602</refsect1>
2603</refentry>
2604
2605<refentry id="API-sata-link-resume">
2606<refentryinfo>
2607 <title>LINUX</title>
2608 <productname>Kernel Hackers Manual</productname>
2609 <date>July 2017</date>
2610</refentryinfo>
2611<refmeta>
2612 <refentrytitle><phrase>sata_link_resume</phrase></refentrytitle>
2613 <manvolnum>9</manvolnum>
2614 <refmiscinfo class="version">4.1.27</refmiscinfo>
2615</refmeta>
2616<refnamediv>
2617 <refname>sata_link_resume</refname>
2618 <refpurpose>
2619     resume SATA link
2620 </refpurpose>
2621</refnamediv>
2622<refsynopsisdiv>
2623 <title>Synopsis</title>
2624  <funcsynopsis><funcprototype>
2625   <funcdef>int <function>sata_link_resume </function></funcdef>
2626   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2627   <paramdef>const unsigned long * <parameter>params</parameter></paramdef>
2628   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
2629  </funcprototype></funcsynopsis>
2630</refsynopsisdiv>
2631<refsect1>
2632 <title>Arguments</title>
2633 <variablelist>
2634  <varlistentry>
2635   <term><parameter>link</parameter></term>
2636   <listitem>
2637    <para>
2638     ATA link to resume SATA
2639    </para>
2640   </listitem>
2641  </varlistentry>
2642  <varlistentry>
2643   <term><parameter>params</parameter></term>
2644   <listitem>
2645    <para>
2646     timing parameters { interval, duratinon, timeout } in msec
2647    </para>
2648   </listitem>
2649  </varlistentry>
2650  <varlistentry>
2651   <term><parameter>deadline</parameter></term>
2652   <listitem>
2653    <para>
2654     deadline jiffies for the operation
2655    </para>
2656   </listitem>
2657  </varlistentry>
2658 </variablelist>
2659</refsect1>
2660<refsect1>
2661<title>Description</title>
2662<para>
2663   Resume SATA phy <parameter>link</parameter> and debounce it.
2664</para>
2665</refsect1>
2666<refsect1>
2667<title>LOCKING</title>
2668<para>
2669   Kernel thread context (may sleep)
2670</para>
2671</refsect1>
2672<refsect1>
2673<title>RETURNS</title>
2674<para>
2675   0 on success, -errno on failure.
2676</para>
2677</refsect1>
2678</refentry>
2679
2680<refentry id="API-sata-link-scr-lpm">
2681<refentryinfo>
2682 <title>LINUX</title>
2683 <productname>Kernel Hackers Manual</productname>
2684 <date>July 2017</date>
2685</refentryinfo>
2686<refmeta>
2687 <refentrytitle><phrase>sata_link_scr_lpm</phrase></refentrytitle>
2688 <manvolnum>9</manvolnum>
2689 <refmiscinfo class="version">4.1.27</refmiscinfo>
2690</refmeta>
2691<refnamediv>
2692 <refname>sata_link_scr_lpm</refname>
2693 <refpurpose>
2694     manipulate SControl IPM and SPM fields
2695 </refpurpose>
2696</refnamediv>
2697<refsynopsisdiv>
2698 <title>Synopsis</title>
2699  <funcsynopsis><funcprototype>
2700   <funcdef>int <function>sata_link_scr_lpm </function></funcdef>
2701   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2702   <paramdef>enum ata_lpm_policy <parameter>policy</parameter></paramdef>
2703   <paramdef>bool <parameter>spm_wakeup</parameter></paramdef>
2704  </funcprototype></funcsynopsis>
2705</refsynopsisdiv>
2706<refsect1>
2707 <title>Arguments</title>
2708 <variablelist>
2709  <varlistentry>
2710   <term><parameter>link</parameter></term>
2711   <listitem>
2712    <para>
2713     ATA link to manipulate SControl for
2714    </para>
2715   </listitem>
2716  </varlistentry>
2717  <varlistentry>
2718   <term><parameter>policy</parameter></term>
2719   <listitem>
2720    <para>
2721     LPM policy to configure
2722    </para>
2723   </listitem>
2724  </varlistentry>
2725  <varlistentry>
2726   <term><parameter>spm_wakeup</parameter></term>
2727   <listitem>
2728    <para>
2729     initiate LPM transition to active state
2730    </para>
2731   </listitem>
2732  </varlistentry>
2733 </variablelist>
2734</refsect1>
2735<refsect1>
2736<title>Description</title>
2737<para>
2738   Manipulate the IPM field of the SControl register of <parameter>link</parameter>
2739   according to <parameter>policy</parameter>.  If <parameter>policy</parameter> is ATA_LPM_MAX_POWER and
2740   <parameter>spm_wakeup</parameter> is <constant>true</constant>, the SPM field is manipulated to wake up
2741   the link.  This function also clears PHYRDY_CHG before
2742   returning.
2743</para>
2744</refsect1>
2745<refsect1>
2746<title>LOCKING</title>
2747<para>
2748   EH context.
2749</para>
2750</refsect1>
2751<refsect1>
2752<title>RETURNS</title>
2753<para>
2754   0 on succes, -errno otherwise.
2755</para>
2756</refsect1>
2757</refentry>
2758
2759<refentry id="API-ata-std-prereset">
2760<refentryinfo>
2761 <title>LINUX</title>
2762 <productname>Kernel Hackers Manual</productname>
2763 <date>July 2017</date>
2764</refentryinfo>
2765<refmeta>
2766 <refentrytitle><phrase>ata_std_prereset</phrase></refentrytitle>
2767 <manvolnum>9</manvolnum>
2768 <refmiscinfo class="version">4.1.27</refmiscinfo>
2769</refmeta>
2770<refnamediv>
2771 <refname>ata_std_prereset</refname>
2772 <refpurpose>
2773     prepare for reset
2774 </refpurpose>
2775</refnamediv>
2776<refsynopsisdiv>
2777 <title>Synopsis</title>
2778  <funcsynopsis><funcprototype>
2779   <funcdef>int <function>ata_std_prereset </function></funcdef>
2780   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2781   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
2782  </funcprototype></funcsynopsis>
2783</refsynopsisdiv>
2784<refsect1>
2785 <title>Arguments</title>
2786 <variablelist>
2787  <varlistentry>
2788   <term><parameter>link</parameter></term>
2789   <listitem>
2790    <para>
2791     ATA link to be reset
2792    </para>
2793   </listitem>
2794  </varlistentry>
2795  <varlistentry>
2796   <term><parameter>deadline</parameter></term>
2797   <listitem>
2798    <para>
2799     deadline jiffies for the operation
2800    </para>
2801   </listitem>
2802  </varlistentry>
2803 </variablelist>
2804</refsect1>
2805<refsect1>
2806<title>Description</title>
2807<para>
2808   <parameter>link</parameter> is about to be reset.  Initialize it.  Failure from
2809   prereset makes libata abort whole reset sequence and give up
2810   that port, so prereset should be best-effort.  It does its
2811   best to prepare for reset sequence but if things go wrong, it
2812   should just whine, not fail.
2813</para>
2814</refsect1>
2815<refsect1>
2816<title>LOCKING</title>
2817<para>
2818   Kernel thread context (may sleep)
2819</para>
2820</refsect1>
2821<refsect1>
2822<title>RETURNS</title>
2823<para>
2824   0 on success, -errno otherwise.
2825</para>
2826</refsect1>
2827</refentry>
2828
2829<refentry id="API-sata-link-hardreset">
2830<refentryinfo>
2831 <title>LINUX</title>
2832 <productname>Kernel Hackers Manual</productname>
2833 <date>July 2017</date>
2834</refentryinfo>
2835<refmeta>
2836 <refentrytitle><phrase>sata_link_hardreset</phrase></refentrytitle>
2837 <manvolnum>9</manvolnum>
2838 <refmiscinfo class="version">4.1.27</refmiscinfo>
2839</refmeta>
2840<refnamediv>
2841 <refname>sata_link_hardreset</refname>
2842 <refpurpose>
2843     reset link via SATA phy reset
2844 </refpurpose>
2845</refnamediv>
2846<refsynopsisdiv>
2847 <title>Synopsis</title>
2848  <funcsynopsis><funcprototype>
2849   <funcdef>int <function>sata_link_hardreset </function></funcdef>
2850   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2851   <paramdef>const unsigned long * <parameter>timing</parameter></paramdef>
2852   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
2853   <paramdef>bool * <parameter>online</parameter></paramdef>
2854   <paramdef>int (*<parameter>check_ready</parameter>)
2855     <funcparams>struct ata_link *</funcparams></paramdef>
2856  </funcprototype></funcsynopsis>
2857</refsynopsisdiv>
2858<refsect1>
2859 <title>Arguments</title>
2860 <variablelist>
2861  <varlistentry>
2862   <term><parameter>link</parameter></term>
2863   <listitem>
2864    <para>
2865     link to reset
2866    </para>
2867   </listitem>
2868  </varlistentry>
2869  <varlistentry>
2870   <term><parameter>timing</parameter></term>
2871   <listitem>
2872    <para>
2873     timing parameters { interval, duratinon, timeout } in msec
2874    </para>
2875   </listitem>
2876  </varlistentry>
2877  <varlistentry>
2878   <term><parameter>deadline</parameter></term>
2879   <listitem>
2880    <para>
2881     deadline jiffies for the operation
2882    </para>
2883   </listitem>
2884  </varlistentry>
2885  <varlistentry>
2886   <term><parameter>online</parameter></term>
2887   <listitem>
2888    <para>
2889     optional out parameter indicating link onlineness
2890    </para>
2891   </listitem>
2892  </varlistentry>
2893  <varlistentry>
2894   <term><parameter>check_ready</parameter></term>
2895   <listitem>
2896    <para>
2897     optional callback to check link readiness
2898    </para>
2899   </listitem>
2900  </varlistentry>
2901 </variablelist>
2902</refsect1>
2903<refsect1>
2904<title>Description</title>
2905<para>
2906   SATA phy-reset <parameter>link</parameter> using DET bits of SControl register.
2907   After hardreset, link readiness is waited upon using
2908   <function>ata_wait_ready</function> if <parameter>check_ready</parameter> is specified.  LLDs are
2909   allowed to not specify <parameter>check_ready</parameter> and wait itself after this
2910   function returns.  Device classification is LLD's
2911   responsibility.
2912   </para><para>
2913
2914   *<parameter>online</parameter> is set to one iff reset succeeded and <parameter>link</parameter> is online
2915   after reset.
2916</para>
2917</refsect1>
2918<refsect1>
2919<title>LOCKING</title>
2920<para>
2921   Kernel thread context (may sleep)
2922</para>
2923</refsect1>
2924<refsect1>
2925<title>RETURNS</title>
2926<para>
2927   0 on success, -errno otherwise.
2928</para>
2929</refsect1>
2930</refentry>
2931
2932<refentry id="API-sata-std-hardreset">
2933<refentryinfo>
2934 <title>LINUX</title>
2935 <productname>Kernel Hackers Manual</productname>
2936 <date>July 2017</date>
2937</refentryinfo>
2938<refmeta>
2939 <refentrytitle><phrase>sata_std_hardreset</phrase></refentrytitle>
2940 <manvolnum>9</manvolnum>
2941 <refmiscinfo class="version">4.1.27</refmiscinfo>
2942</refmeta>
2943<refnamediv>
2944 <refname>sata_std_hardreset</refname>
2945 <refpurpose>
2946     COMRESET w/o waiting or classification
2947 </refpurpose>
2948</refnamediv>
2949<refsynopsisdiv>
2950 <title>Synopsis</title>
2951  <funcsynopsis><funcprototype>
2952   <funcdef>int <function>sata_std_hardreset </function></funcdef>
2953   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
2954   <paramdef>unsigned int * <parameter>class</parameter></paramdef>
2955   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
2956  </funcprototype></funcsynopsis>
2957</refsynopsisdiv>
2958<refsect1>
2959 <title>Arguments</title>
2960 <variablelist>
2961  <varlistentry>
2962   <term><parameter>link</parameter></term>
2963   <listitem>
2964    <para>
2965     link to reset
2966    </para>
2967   </listitem>
2968  </varlistentry>
2969  <varlistentry>
2970   <term><parameter>class</parameter></term>
2971   <listitem>
2972    <para>
2973     resulting class of attached device
2974    </para>
2975   </listitem>
2976  </varlistentry>
2977  <varlistentry>
2978   <term><parameter>deadline</parameter></term>
2979   <listitem>
2980    <para>
2981     deadline jiffies for the operation
2982    </para>
2983   </listitem>
2984  </varlistentry>
2985 </variablelist>
2986</refsect1>
2987<refsect1>
2988<title>Description</title>
2989<para>
2990   Standard SATA COMRESET w/o waiting or classification.
2991</para>
2992</refsect1>
2993<refsect1>
2994<title>LOCKING</title>
2995<para>
2996   Kernel thread context (may sleep)
2997</para>
2998</refsect1>
2999<refsect1>
3000<title>RETURNS</title>
3001<para>
3002   0 if link offline, -EAGAIN if link online, -errno on errors.
3003</para>
3004</refsect1>
3005</refentry>
3006
3007<refentry id="API-ata-std-postreset">
3008<refentryinfo>
3009 <title>LINUX</title>
3010 <productname>Kernel Hackers Manual</productname>
3011 <date>July 2017</date>
3012</refentryinfo>
3013<refmeta>
3014 <refentrytitle><phrase>ata_std_postreset</phrase></refentrytitle>
3015 <manvolnum>9</manvolnum>
3016 <refmiscinfo class="version">4.1.27</refmiscinfo>
3017</refmeta>
3018<refnamediv>
3019 <refname>ata_std_postreset</refname>
3020 <refpurpose>
3021     standard postreset callback
3022 </refpurpose>
3023</refnamediv>
3024<refsynopsisdiv>
3025 <title>Synopsis</title>
3026  <funcsynopsis><funcprototype>
3027   <funcdef>void <function>ata_std_postreset </function></funcdef>
3028   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3029   <paramdef>unsigned int * <parameter>classes</parameter></paramdef>
3030  </funcprototype></funcsynopsis>
3031</refsynopsisdiv>
3032<refsect1>
3033 <title>Arguments</title>
3034 <variablelist>
3035  <varlistentry>
3036   <term><parameter>link</parameter></term>
3037   <listitem>
3038    <para>
3039     the target ata_link
3040    </para>
3041   </listitem>
3042  </varlistentry>
3043  <varlistentry>
3044   <term><parameter>classes</parameter></term>
3045   <listitem>
3046    <para>
3047     classes of attached devices
3048    </para>
3049   </listitem>
3050  </varlistentry>
3051 </variablelist>
3052</refsect1>
3053<refsect1>
3054<title>Description</title>
3055<para>
3056   This function is invoked after a successful reset.  Note that
3057   the device might have been reset more than once using
3058   different reset methods before postreset is invoked.
3059</para>
3060</refsect1>
3061<refsect1>
3062<title>LOCKING</title>
3063<para>
3064   Kernel thread context (may sleep)
3065</para>
3066</refsect1>
3067</refentry>
3068
3069<refentry id="API-ata-dev-set-feature">
3070<refentryinfo>
3071 <title>LINUX</title>
3072 <productname>Kernel Hackers Manual</productname>
3073 <date>July 2017</date>
3074</refentryinfo>
3075<refmeta>
3076 <refentrytitle><phrase>ata_dev_set_feature</phrase></refentrytitle>
3077 <manvolnum>9</manvolnum>
3078 <refmiscinfo class="version">4.1.27</refmiscinfo>
3079</refmeta>
3080<refnamediv>
3081 <refname>ata_dev_set_feature</refname>
3082 <refpurpose>
3083     Issue SET FEATURES - SATA FEATURES
3084 </refpurpose>
3085</refnamediv>
3086<refsynopsisdiv>
3087 <title>Synopsis</title>
3088  <funcsynopsis><funcprototype>
3089   <funcdef>unsigned int <function>ata_dev_set_feature </function></funcdef>
3090   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
3091   <paramdef>u8 <parameter>enable</parameter></paramdef>
3092   <paramdef>u8 <parameter>feature</parameter></paramdef>
3093  </funcprototype></funcsynopsis>
3094</refsynopsisdiv>
3095<refsect1>
3096 <title>Arguments</title>
3097 <variablelist>
3098  <varlistentry>
3099   <term><parameter>dev</parameter></term>
3100   <listitem>
3101    <para>
3102     Device to which command will be sent
3103    </para>
3104   </listitem>
3105  </varlistentry>
3106  <varlistentry>
3107   <term><parameter>enable</parameter></term>
3108   <listitem>
3109    <para>
3110     Whether to enable or disable the feature
3111    </para>
3112   </listitem>
3113  </varlistentry>
3114  <varlistentry>
3115   <term><parameter>feature</parameter></term>
3116   <listitem>
3117    <para>
3118     The sector count represents the feature to set
3119    </para>
3120   </listitem>
3121  </varlistentry>
3122 </variablelist>
3123</refsect1>
3124<refsect1>
3125<title>Description</title>
3126<para>
3127   Issue SET FEATURES - SATA FEATURES command to device <parameter>dev</parameter>
3128   on port <parameter>ap</parameter> with sector count
3129</para>
3130</refsect1>
3131<refsect1>
3132<title>LOCKING</title>
3133<para>
3134   PCI/etc. bus probe sem.
3135</para>
3136</refsect1>
3137<refsect1>
3138<title>RETURNS</title>
3139<para>
3140   0 on success, AC_ERR_* mask otherwise.
3141</para>
3142</refsect1>
3143</refentry>
3144
3145<refentry id="API-ata-std-qc-defer">
3146<refentryinfo>
3147 <title>LINUX</title>
3148 <productname>Kernel Hackers Manual</productname>
3149 <date>July 2017</date>
3150</refentryinfo>
3151<refmeta>
3152 <refentrytitle><phrase>ata_std_qc_defer</phrase></refentrytitle>
3153 <manvolnum>9</manvolnum>
3154 <refmiscinfo class="version">4.1.27</refmiscinfo>
3155</refmeta>
3156<refnamediv>
3157 <refname>ata_std_qc_defer</refname>
3158 <refpurpose>
3159     Check whether a qc needs to be deferred
3160 </refpurpose>
3161</refnamediv>
3162<refsynopsisdiv>
3163 <title>Synopsis</title>
3164  <funcsynopsis><funcprototype>
3165   <funcdef>int <function>ata_std_qc_defer </function></funcdef>
3166   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
3167  </funcprototype></funcsynopsis>
3168</refsynopsisdiv>
3169<refsect1>
3170 <title>Arguments</title>
3171 <variablelist>
3172  <varlistentry>
3173   <term><parameter>qc</parameter></term>
3174   <listitem>
3175    <para>
3176     ATA command in question
3177    </para>
3178   </listitem>
3179  </varlistentry>
3180 </variablelist>
3181</refsect1>
3182<refsect1>
3183<title>Description</title>
3184<para>
3185   Non-NCQ commands cannot run with any other command, NCQ or
3186   not.  As upper layer only knows the queue depth, we are
3187   responsible for maintaining exclusion.  This function checks
3188   whether a new command <parameter>qc</parameter> can be issued.
3189</para>
3190</refsect1>
3191<refsect1>
3192<title>LOCKING</title>
3193<para>
3194   spin_lock_irqsave(host lock)
3195</para>
3196</refsect1>
3197<refsect1>
3198<title>RETURNS</title>
3199<para>
3200   ATA_DEFER_* if deferring is needed, 0 otherwise.
3201</para>
3202</refsect1>
3203</refentry>
3204
3205<refentry id="API-ata-sg-init">
3206<refentryinfo>
3207 <title>LINUX</title>
3208 <productname>Kernel Hackers Manual</productname>
3209 <date>July 2017</date>
3210</refentryinfo>
3211<refmeta>
3212 <refentrytitle><phrase>ata_sg_init</phrase></refentrytitle>
3213 <manvolnum>9</manvolnum>
3214 <refmiscinfo class="version">4.1.27</refmiscinfo>
3215</refmeta>
3216<refnamediv>
3217 <refname>ata_sg_init</refname>
3218 <refpurpose>
3219     Associate command with scatter-gather table.
3220 </refpurpose>
3221</refnamediv>
3222<refsynopsisdiv>
3223 <title>Synopsis</title>
3224  <funcsynopsis><funcprototype>
3225   <funcdef>void <function>ata_sg_init </function></funcdef>
3226   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
3227   <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef>
3228   <paramdef>unsigned int <parameter>n_elem</parameter></paramdef>
3229  </funcprototype></funcsynopsis>
3230</refsynopsisdiv>
3231<refsect1>
3232 <title>Arguments</title>
3233 <variablelist>
3234  <varlistentry>
3235   <term><parameter>qc</parameter></term>
3236   <listitem>
3237    <para>
3238     Command to be associated
3239    </para>
3240   </listitem>
3241  </varlistentry>
3242  <varlistentry>
3243   <term><parameter>sg</parameter></term>
3244   <listitem>
3245    <para>
3246     Scatter-gather table.
3247    </para>
3248   </listitem>
3249  </varlistentry>
3250  <varlistentry>
3251   <term><parameter>n_elem</parameter></term>
3252   <listitem>
3253    <para>
3254     Number of elements in s/g table.
3255    </para>
3256   </listitem>
3257  </varlistentry>
3258 </variablelist>
3259</refsect1>
3260<refsect1>
3261<title>Description</title>
3262<para>
3263   Initialize the data-related elements of queued_cmd <parameter>qc</parameter>
3264   to point to a scatter-gather table <parameter>sg</parameter>, containing <parameter>n_elem</parameter>
3265   elements.
3266</para>
3267</refsect1>
3268<refsect1>
3269<title>LOCKING</title>
3270<para>
3271   spin_lock_irqsave(host lock)
3272</para>
3273</refsect1>
3274</refentry>
3275
3276<refentry id="API-ata-qc-complete">
3277<refentryinfo>
3278 <title>LINUX</title>
3279 <productname>Kernel Hackers Manual</productname>
3280 <date>July 2017</date>
3281</refentryinfo>
3282<refmeta>
3283 <refentrytitle><phrase>ata_qc_complete</phrase></refentrytitle>
3284 <manvolnum>9</manvolnum>
3285 <refmiscinfo class="version">4.1.27</refmiscinfo>
3286</refmeta>
3287<refnamediv>
3288 <refname>ata_qc_complete</refname>
3289 <refpurpose>
3290     Complete an active ATA command
3291 </refpurpose>
3292</refnamediv>
3293<refsynopsisdiv>
3294 <title>Synopsis</title>
3295  <funcsynopsis><funcprototype>
3296   <funcdef>void <function>ata_qc_complete </function></funcdef>
3297   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
3298  </funcprototype></funcsynopsis>
3299</refsynopsisdiv>
3300<refsect1>
3301 <title>Arguments</title>
3302 <variablelist>
3303  <varlistentry>
3304   <term><parameter>qc</parameter></term>
3305   <listitem>
3306    <para>
3307     Command to complete
3308    </para>
3309   </listitem>
3310  </varlistentry>
3311 </variablelist>
3312</refsect1>
3313<refsect1>
3314<title>Description</title>
3315<para>
3316   Indicate to the mid and upper layers that an ATA command has
3317   completed, with either an ok or not-ok status.
3318   </para><para>
3319
3320   Refrain from calling this function multiple times when
3321   successfully completing multiple NCQ commands.
3322   <function>ata_qc_complete_multiple</function> should be used instead, which will
3323   properly update IRQ expect state.
3324</para>
3325</refsect1>
3326<refsect1>
3327<title>LOCKING</title>
3328<para>
3329   spin_lock_irqsave(host lock)
3330</para>
3331</refsect1>
3332</refentry>
3333
3334<refentry id="API-ata-qc-complete-multiple">
3335<refentryinfo>
3336 <title>LINUX</title>
3337 <productname>Kernel Hackers Manual</productname>
3338 <date>July 2017</date>
3339</refentryinfo>
3340<refmeta>
3341 <refentrytitle><phrase>ata_qc_complete_multiple</phrase></refentrytitle>
3342 <manvolnum>9</manvolnum>
3343 <refmiscinfo class="version">4.1.27</refmiscinfo>
3344</refmeta>
3345<refnamediv>
3346 <refname>ata_qc_complete_multiple</refname>
3347 <refpurpose>
3348     Complete multiple qcs successfully
3349 </refpurpose>
3350</refnamediv>
3351<refsynopsisdiv>
3352 <title>Synopsis</title>
3353  <funcsynopsis><funcprototype>
3354   <funcdef>int <function>ata_qc_complete_multiple </function></funcdef>
3355   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
3356   <paramdef>u32 <parameter>qc_active</parameter></paramdef>
3357  </funcprototype></funcsynopsis>
3358</refsynopsisdiv>
3359<refsect1>
3360 <title>Arguments</title>
3361 <variablelist>
3362  <varlistentry>
3363   <term><parameter>ap</parameter></term>
3364   <listitem>
3365    <para>
3366     port in question
3367    </para>
3368   </listitem>
3369  </varlistentry>
3370  <varlistentry>
3371   <term><parameter>qc_active</parameter></term>
3372   <listitem>
3373    <para>
3374     new qc_active mask
3375    </para>
3376   </listitem>
3377  </varlistentry>
3378 </variablelist>
3379</refsect1>
3380<refsect1>
3381<title>Description</title>
3382<para>
3383   Complete in-flight commands.  This functions is meant to be
3384   called from low-level driver's interrupt routine to complete
3385   requests normally.  ap-&gt;qc_active and <parameter>qc_active</parameter> is compared
3386   and commands are completed accordingly.
3387   </para><para>
3388
3389   Always use this function when completing multiple NCQ commands
3390   from IRQ handlers instead of calling <function>ata_qc_complete</function>
3391   multiple times to keep IRQ expect status properly in sync.
3392</para>
3393</refsect1>
3394<refsect1>
3395<title>LOCKING</title>
3396<para>
3397   spin_lock_irqsave(host lock)
3398</para>
3399</refsect1>
3400<refsect1>
3401<title>RETURNS</title>
3402<para>
3403   Number of completed commands on success, -errno otherwise.
3404</para>
3405</refsect1>
3406</refentry>
3407
3408<refentry id="API-sata-scr-valid">
3409<refentryinfo>
3410 <title>LINUX</title>
3411 <productname>Kernel Hackers Manual</productname>
3412 <date>July 2017</date>
3413</refentryinfo>
3414<refmeta>
3415 <refentrytitle><phrase>sata_scr_valid</phrase></refentrytitle>
3416 <manvolnum>9</manvolnum>
3417 <refmiscinfo class="version">4.1.27</refmiscinfo>
3418</refmeta>
3419<refnamediv>
3420 <refname>sata_scr_valid</refname>
3421 <refpurpose>
3422     test whether SCRs are accessible
3423 </refpurpose>
3424</refnamediv>
3425<refsynopsisdiv>
3426 <title>Synopsis</title>
3427  <funcsynopsis><funcprototype>
3428   <funcdef>int <function>sata_scr_valid </function></funcdef>
3429   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3430  </funcprototype></funcsynopsis>
3431</refsynopsisdiv>
3432<refsect1>
3433 <title>Arguments</title>
3434 <variablelist>
3435  <varlistentry>
3436   <term><parameter>link</parameter></term>
3437   <listitem>
3438    <para>
3439     ATA link to test SCR accessibility for
3440    </para>
3441   </listitem>
3442  </varlistentry>
3443 </variablelist>
3444</refsect1>
3445<refsect1>
3446<title>Description</title>
3447<para>
3448   Test whether SCRs are accessible for <parameter>link</parameter>.
3449</para>
3450</refsect1>
3451<refsect1>
3452<title>LOCKING</title>
3453<para>
3454   None.
3455</para>
3456</refsect1>
3457<refsect1>
3458<title>RETURNS</title>
3459<para>
3460   1 if SCRs are accessible, 0 otherwise.
3461</para>
3462</refsect1>
3463</refentry>
3464
3465<refentry id="API-sata-scr-read">
3466<refentryinfo>
3467 <title>LINUX</title>
3468 <productname>Kernel Hackers Manual</productname>
3469 <date>July 2017</date>
3470</refentryinfo>
3471<refmeta>
3472 <refentrytitle><phrase>sata_scr_read</phrase></refentrytitle>
3473 <manvolnum>9</manvolnum>
3474 <refmiscinfo class="version">4.1.27</refmiscinfo>
3475</refmeta>
3476<refnamediv>
3477 <refname>sata_scr_read</refname>
3478 <refpurpose>
3479     read SCR register of the specified port
3480 </refpurpose>
3481</refnamediv>
3482<refsynopsisdiv>
3483 <title>Synopsis</title>
3484  <funcsynopsis><funcprototype>
3485   <funcdef>int <function>sata_scr_read </function></funcdef>
3486   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3487   <paramdef>int <parameter>reg</parameter></paramdef>
3488   <paramdef>u32 * <parameter>val</parameter></paramdef>
3489  </funcprototype></funcsynopsis>
3490</refsynopsisdiv>
3491<refsect1>
3492 <title>Arguments</title>
3493 <variablelist>
3494  <varlistentry>
3495   <term><parameter>link</parameter></term>
3496   <listitem>
3497    <para>
3498     ATA link to read SCR for
3499    </para>
3500   </listitem>
3501  </varlistentry>
3502  <varlistentry>
3503   <term><parameter>reg</parameter></term>
3504   <listitem>
3505    <para>
3506     SCR to read
3507    </para>
3508   </listitem>
3509  </varlistentry>
3510  <varlistentry>
3511   <term><parameter>val</parameter></term>
3512   <listitem>
3513    <para>
3514     Place to store read value
3515    </para>
3516   </listitem>
3517  </varlistentry>
3518 </variablelist>
3519</refsect1>
3520<refsect1>
3521<title>Description</title>
3522<para>
3523   Read SCR register <parameter>reg</parameter> of <parameter>link</parameter> into *<parameter>val</parameter>.  This function is
3524   guaranteed to succeed if <parameter>link</parameter> is ap-&gt;link, the cable type of
3525   the port is SATA and the port implements -&gt;scr_read.
3526</para>
3527</refsect1>
3528<refsect1>
3529<title>LOCKING</title>
3530<para>
3531   None if <parameter>link</parameter> is ap-&gt;link.  Kernel thread context otherwise.
3532</para>
3533</refsect1>
3534<refsect1>
3535<title>RETURNS</title>
3536<para>
3537   0 on success, negative errno on failure.
3538</para>
3539</refsect1>
3540</refentry>
3541
3542<refentry id="API-sata-scr-write">
3543<refentryinfo>
3544 <title>LINUX</title>
3545 <productname>Kernel Hackers Manual</productname>
3546 <date>July 2017</date>
3547</refentryinfo>
3548<refmeta>
3549 <refentrytitle><phrase>sata_scr_write</phrase></refentrytitle>
3550 <manvolnum>9</manvolnum>
3551 <refmiscinfo class="version">4.1.27</refmiscinfo>
3552</refmeta>
3553<refnamediv>
3554 <refname>sata_scr_write</refname>
3555 <refpurpose>
3556     write SCR register of the specified port
3557 </refpurpose>
3558</refnamediv>
3559<refsynopsisdiv>
3560 <title>Synopsis</title>
3561  <funcsynopsis><funcprototype>
3562   <funcdef>int <function>sata_scr_write </function></funcdef>
3563   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3564   <paramdef>int <parameter>reg</parameter></paramdef>
3565   <paramdef>u32 <parameter>val</parameter></paramdef>
3566  </funcprototype></funcsynopsis>
3567</refsynopsisdiv>
3568<refsect1>
3569 <title>Arguments</title>
3570 <variablelist>
3571  <varlistentry>
3572   <term><parameter>link</parameter></term>
3573   <listitem>
3574    <para>
3575     ATA link to write SCR for
3576    </para>
3577   </listitem>
3578  </varlistentry>
3579  <varlistentry>
3580   <term><parameter>reg</parameter></term>
3581   <listitem>
3582    <para>
3583     SCR to write
3584    </para>
3585   </listitem>
3586  </varlistentry>
3587  <varlistentry>
3588   <term><parameter>val</parameter></term>
3589   <listitem>
3590    <para>
3591     value to write
3592    </para>
3593   </listitem>
3594  </varlistentry>
3595 </variablelist>
3596</refsect1>
3597<refsect1>
3598<title>Description</title>
3599<para>
3600   Write <parameter>val</parameter> to SCR register <parameter>reg</parameter> of <parameter>link</parameter>.  This function is
3601   guaranteed to succeed if <parameter>link</parameter> is ap-&gt;link, the cable type of
3602   the port is SATA and the port implements -&gt;scr_read.
3603</para>
3604</refsect1>
3605<refsect1>
3606<title>LOCKING</title>
3607<para>
3608   None if <parameter>link</parameter> is ap-&gt;link.  Kernel thread context otherwise.
3609</para>
3610</refsect1>
3611<refsect1>
3612<title>RETURNS</title>
3613<para>
3614   0 on success, negative errno on failure.
3615</para>
3616</refsect1>
3617</refentry>
3618
3619<refentry id="API-sata-scr-write-flush">
3620<refentryinfo>
3621 <title>LINUX</title>
3622 <productname>Kernel Hackers Manual</productname>
3623 <date>July 2017</date>
3624</refentryinfo>
3625<refmeta>
3626 <refentrytitle><phrase>sata_scr_write_flush</phrase></refentrytitle>
3627 <manvolnum>9</manvolnum>
3628 <refmiscinfo class="version">4.1.27</refmiscinfo>
3629</refmeta>
3630<refnamediv>
3631 <refname>sata_scr_write_flush</refname>
3632 <refpurpose>
3633     write SCR register of the specified port and flush
3634 </refpurpose>
3635</refnamediv>
3636<refsynopsisdiv>
3637 <title>Synopsis</title>
3638  <funcsynopsis><funcprototype>
3639   <funcdef>int <function>sata_scr_write_flush </function></funcdef>
3640   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3641   <paramdef>int <parameter>reg</parameter></paramdef>
3642   <paramdef>u32 <parameter>val</parameter></paramdef>
3643  </funcprototype></funcsynopsis>
3644</refsynopsisdiv>
3645<refsect1>
3646 <title>Arguments</title>
3647 <variablelist>
3648  <varlistentry>
3649   <term><parameter>link</parameter></term>
3650   <listitem>
3651    <para>
3652     ATA link to write SCR for
3653    </para>
3654   </listitem>
3655  </varlistentry>
3656  <varlistentry>
3657   <term><parameter>reg</parameter></term>
3658   <listitem>
3659    <para>
3660     SCR to write
3661    </para>
3662   </listitem>
3663  </varlistentry>
3664  <varlistentry>
3665   <term><parameter>val</parameter></term>
3666   <listitem>
3667    <para>
3668     value to write
3669    </para>
3670   </listitem>
3671  </varlistentry>
3672 </variablelist>
3673</refsect1>
3674<refsect1>
3675<title>Description</title>
3676<para>
3677   This function is identical to <function>sata_scr_write</function> except that this
3678   function performs flush after writing to the register.
3679</para>
3680</refsect1>
3681<refsect1>
3682<title>LOCKING</title>
3683<para>
3684   None if <parameter>link</parameter> is ap-&gt;link.  Kernel thread context otherwise.
3685</para>
3686</refsect1>
3687<refsect1>
3688<title>RETURNS</title>
3689<para>
3690   0 on success, negative errno on failure.
3691</para>
3692</refsect1>
3693</refentry>
3694
3695<refentry id="API-ata-link-online">
3696<refentryinfo>
3697 <title>LINUX</title>
3698 <productname>Kernel Hackers Manual</productname>
3699 <date>July 2017</date>
3700</refentryinfo>
3701<refmeta>
3702 <refentrytitle><phrase>ata_link_online</phrase></refentrytitle>
3703 <manvolnum>9</manvolnum>
3704 <refmiscinfo class="version">4.1.27</refmiscinfo>
3705</refmeta>
3706<refnamediv>
3707 <refname>ata_link_online</refname>
3708 <refpurpose>
3709     test whether the given link is online
3710 </refpurpose>
3711</refnamediv>
3712<refsynopsisdiv>
3713 <title>Synopsis</title>
3714  <funcsynopsis><funcprototype>
3715   <funcdef>bool <function>ata_link_online </function></funcdef>
3716   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3717  </funcprototype></funcsynopsis>
3718</refsynopsisdiv>
3719<refsect1>
3720 <title>Arguments</title>
3721 <variablelist>
3722  <varlistentry>
3723   <term><parameter>link</parameter></term>
3724   <listitem>
3725    <para>
3726     ATA link to test
3727    </para>
3728   </listitem>
3729  </varlistentry>
3730 </variablelist>
3731</refsect1>
3732<refsect1>
3733<title>Description</title>
3734<para>
3735   Test whether <parameter>link</parameter> is online.  This is identical to
3736   <function>ata_phys_link_online</function> when there's no slave link.  When
3737   there's a slave link, this function should only be called on
3738   the master link and will return true if any of M/S links is
3739   online.
3740</para>
3741</refsect1>
3742<refsect1>
3743<title>LOCKING</title>
3744<para>
3745   None.
3746</para>
3747</refsect1>
3748<refsect1>
3749<title>RETURNS</title>
3750<para>
3751   True if the port online status is available and online.
3752</para>
3753</refsect1>
3754</refentry>
3755
3756<refentry id="API-ata-link-offline">
3757<refentryinfo>
3758 <title>LINUX</title>
3759 <productname>Kernel Hackers Manual</productname>
3760 <date>July 2017</date>
3761</refentryinfo>
3762<refmeta>
3763 <refentrytitle><phrase>ata_link_offline</phrase></refentrytitle>
3764 <manvolnum>9</manvolnum>
3765 <refmiscinfo class="version">4.1.27</refmiscinfo>
3766</refmeta>
3767<refnamediv>
3768 <refname>ata_link_offline</refname>
3769 <refpurpose>
3770     test whether the given link is offline
3771 </refpurpose>
3772</refnamediv>
3773<refsynopsisdiv>
3774 <title>Synopsis</title>
3775  <funcsynopsis><funcprototype>
3776   <funcdef>bool <function>ata_link_offline </function></funcdef>
3777   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
3778  </funcprototype></funcsynopsis>
3779</refsynopsisdiv>
3780<refsect1>
3781 <title>Arguments</title>
3782 <variablelist>
3783  <varlistentry>
3784   <term><parameter>link</parameter></term>
3785   <listitem>
3786    <para>
3787     ATA link to test
3788    </para>
3789   </listitem>
3790  </varlistentry>
3791 </variablelist>
3792</refsect1>
3793<refsect1>
3794<title>Description</title>
3795<para>
3796   Test whether <parameter>link</parameter> is offline.  This is identical to
3797   <function>ata_phys_link_offline</function> when there's no slave link.  When
3798   there's a slave link, this function should only be called on
3799   the master link and will return true if both M/S links are
3800   offline.
3801</para>
3802</refsect1>
3803<refsect1>
3804<title>LOCKING</title>
3805<para>
3806   None.
3807</para>
3808</refsect1>
3809<refsect1>
3810<title>RETURNS</title>
3811<para>
3812   True if the port offline status is available and offline.
3813</para>
3814</refsect1>
3815</refentry>
3816
3817<refentry id="API-ata-host-suspend">
3818<refentryinfo>
3819 <title>LINUX</title>
3820 <productname>Kernel Hackers Manual</productname>
3821 <date>July 2017</date>
3822</refentryinfo>
3823<refmeta>
3824 <refentrytitle><phrase>ata_host_suspend</phrase></refentrytitle>
3825 <manvolnum>9</manvolnum>
3826 <refmiscinfo class="version">4.1.27</refmiscinfo>
3827</refmeta>
3828<refnamediv>
3829 <refname>ata_host_suspend</refname>
3830 <refpurpose>
3831     suspend host
3832 </refpurpose>
3833</refnamediv>
3834<refsynopsisdiv>
3835 <title>Synopsis</title>
3836  <funcsynopsis><funcprototype>
3837   <funcdef>int <function>ata_host_suspend </function></funcdef>
3838   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
3839   <paramdef>pm_message_t <parameter>mesg</parameter></paramdef>
3840  </funcprototype></funcsynopsis>
3841</refsynopsisdiv>
3842<refsect1>
3843 <title>Arguments</title>
3844 <variablelist>
3845  <varlistentry>
3846   <term><parameter>host</parameter></term>
3847   <listitem>
3848    <para>
3849     host to suspend
3850    </para>
3851   </listitem>
3852  </varlistentry>
3853  <varlistentry>
3854   <term><parameter>mesg</parameter></term>
3855   <listitem>
3856    <para>
3857     PM message
3858    </para>
3859   </listitem>
3860  </varlistentry>
3861 </variablelist>
3862</refsect1>
3863<refsect1>
3864<title>Description</title>
3865<para>
3866   Suspend <parameter>host</parameter>.  Actual operation is performed by port suspend.
3867</para>
3868</refsect1>
3869</refentry>
3870
3871<refentry id="API-ata-host-resume">
3872<refentryinfo>
3873 <title>LINUX</title>
3874 <productname>Kernel Hackers Manual</productname>
3875 <date>July 2017</date>
3876</refentryinfo>
3877<refmeta>
3878 <refentrytitle><phrase>ata_host_resume</phrase></refentrytitle>
3879 <manvolnum>9</manvolnum>
3880 <refmiscinfo class="version">4.1.27</refmiscinfo>
3881</refmeta>
3882<refnamediv>
3883 <refname>ata_host_resume</refname>
3884 <refpurpose>
3885     resume host
3886 </refpurpose>
3887</refnamediv>
3888<refsynopsisdiv>
3889 <title>Synopsis</title>
3890  <funcsynopsis><funcprototype>
3891   <funcdef>void <function>ata_host_resume </function></funcdef>
3892   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
3893  </funcprototype></funcsynopsis>
3894</refsynopsisdiv>
3895<refsect1>
3896 <title>Arguments</title>
3897 <variablelist>
3898  <varlistentry>
3899   <term><parameter>host</parameter></term>
3900   <listitem>
3901    <para>
3902     host to resume
3903    </para>
3904   </listitem>
3905  </varlistentry>
3906 </variablelist>
3907</refsect1>
3908<refsect1>
3909<title>Description</title>
3910<para>
3911   Resume <parameter>host</parameter>.  Actual operation is performed by port resume.
3912</para>
3913</refsect1>
3914</refentry>
3915
3916<refentry id="API-ata-host-alloc">
3917<refentryinfo>
3918 <title>LINUX</title>
3919 <productname>Kernel Hackers Manual</productname>
3920 <date>July 2017</date>
3921</refentryinfo>
3922<refmeta>
3923 <refentrytitle><phrase>ata_host_alloc</phrase></refentrytitle>
3924 <manvolnum>9</manvolnum>
3925 <refmiscinfo class="version">4.1.27</refmiscinfo>
3926</refmeta>
3927<refnamediv>
3928 <refname>ata_host_alloc</refname>
3929 <refpurpose>
3930     allocate and init basic ATA host resources
3931 </refpurpose>
3932</refnamediv>
3933<refsynopsisdiv>
3934 <title>Synopsis</title>
3935  <funcsynopsis><funcprototype>
3936   <funcdef>struct ata_host * <function>ata_host_alloc </function></funcdef>
3937   <paramdef>struct device * <parameter>dev</parameter></paramdef>
3938   <paramdef>int <parameter>max_ports</parameter></paramdef>
3939  </funcprototype></funcsynopsis>
3940</refsynopsisdiv>
3941<refsect1>
3942 <title>Arguments</title>
3943 <variablelist>
3944  <varlistentry>
3945   <term><parameter>dev</parameter></term>
3946   <listitem>
3947    <para>
3948     generic device this host is associated with
3949    </para>
3950   </listitem>
3951  </varlistentry>
3952  <varlistentry>
3953   <term><parameter>max_ports</parameter></term>
3954   <listitem>
3955    <para>
3956     maximum number of ATA ports associated with this host
3957    </para>
3958   </listitem>
3959  </varlistentry>
3960 </variablelist>
3961</refsect1>
3962<refsect1>
3963<title>Description</title>
3964<para>
3965   Allocate and initialize basic ATA host resources.  LLD calls
3966   this function to allocate a host, initializes it fully and
3967   attaches it using <function>ata_host_register</function>.
3968   </para><para>
3969
3970   <parameter>max_ports</parameter> ports are allocated and host-&gt;n_ports is
3971   initialized to <parameter>max_ports</parameter>.  The caller is allowed to decrease
3972   host-&gt;n_ports before calling <function>ata_host_register</function>.  The unused
3973   ports will be automatically freed on registration.
3974</para>
3975</refsect1>
3976<refsect1>
3977<title>RETURNS</title>
3978<para>
3979   Allocate ATA host on success, NULL on failure.
3980</para>
3981</refsect1>
3982<refsect1>
3983<title>LOCKING</title>
3984<para>
3985   Inherited from calling layer (may sleep).
3986</para>
3987</refsect1>
3988</refentry>
3989
3990<refentry id="API-ata-host-alloc-pinfo">
3991<refentryinfo>
3992 <title>LINUX</title>
3993 <productname>Kernel Hackers Manual</productname>
3994 <date>July 2017</date>
3995</refentryinfo>
3996<refmeta>
3997 <refentrytitle><phrase>ata_host_alloc_pinfo</phrase></refentrytitle>
3998 <manvolnum>9</manvolnum>
3999 <refmiscinfo class="version">4.1.27</refmiscinfo>
4000</refmeta>
4001<refnamediv>
4002 <refname>ata_host_alloc_pinfo</refname>
4003 <refpurpose>
4004     alloc host and init with port_info array
4005 </refpurpose>
4006</refnamediv>
4007<refsynopsisdiv>
4008 <title>Synopsis</title>
4009  <funcsynopsis><funcprototype>
4010   <funcdef>struct ata_host * <function>ata_host_alloc_pinfo </function></funcdef>
4011   <paramdef>struct device * <parameter>dev</parameter></paramdef>
4012   <paramdef>const struct ata_port_info *const * <parameter>ppi</parameter></paramdef>
4013   <paramdef>int <parameter>n_ports</parameter></paramdef>
4014  </funcprototype></funcsynopsis>
4015</refsynopsisdiv>
4016<refsect1>
4017 <title>Arguments</title>
4018 <variablelist>
4019  <varlistentry>
4020   <term><parameter>dev</parameter></term>
4021   <listitem>
4022    <para>
4023     generic device this host is associated with
4024    </para>
4025   </listitem>
4026  </varlistentry>
4027  <varlistentry>
4028   <term><parameter>ppi</parameter></term>
4029   <listitem>
4030    <para>
4031     array of ATA port_info to initialize host with
4032    </para>
4033   </listitem>
4034  </varlistentry>
4035  <varlistentry>
4036   <term><parameter>n_ports</parameter></term>
4037   <listitem>
4038    <para>
4039     number of ATA ports attached to this host
4040    </para>
4041   </listitem>
4042  </varlistentry>
4043 </variablelist>
4044</refsect1>
4045<refsect1>
4046<title>Description</title>
4047<para>
4048   Allocate ATA host and initialize with info from <parameter>ppi</parameter>.  If NULL
4049   terminated, <parameter>ppi</parameter> may contain fewer entries than <parameter>n_ports</parameter>.  The
4050   last entry will be used for the remaining ports.
4051</para>
4052</refsect1>
4053<refsect1>
4054<title>RETURNS</title>
4055<para>
4056   Allocate ATA host on success, NULL on failure.
4057</para>
4058</refsect1>
4059<refsect1>
4060<title>LOCKING</title>
4061<para>
4062   Inherited from calling layer (may sleep).
4063</para>
4064</refsect1>
4065</refentry>
4066
4067<refentry id="API-ata-slave-link-init">
4068<refentryinfo>
4069 <title>LINUX</title>
4070 <productname>Kernel Hackers Manual</productname>
4071 <date>July 2017</date>
4072</refentryinfo>
4073<refmeta>
4074 <refentrytitle><phrase>ata_slave_link_init</phrase></refentrytitle>
4075 <manvolnum>9</manvolnum>
4076 <refmiscinfo class="version">4.1.27</refmiscinfo>
4077</refmeta>
4078<refnamediv>
4079 <refname>ata_slave_link_init</refname>
4080 <refpurpose>
4081     initialize slave link
4082 </refpurpose>
4083</refnamediv>
4084<refsynopsisdiv>
4085 <title>Synopsis</title>
4086  <funcsynopsis><funcprototype>
4087   <funcdef>int <function>ata_slave_link_init </function></funcdef>
4088   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
4089  </funcprototype></funcsynopsis>
4090</refsynopsisdiv>
4091<refsect1>
4092 <title>Arguments</title>
4093 <variablelist>
4094  <varlistentry>
4095   <term><parameter>ap</parameter></term>
4096   <listitem>
4097    <para>
4098     port to initialize slave link for
4099    </para>
4100   </listitem>
4101  </varlistentry>
4102 </variablelist>
4103</refsect1>
4104<refsect1>
4105<title>Description</title>
4106<para>
4107   Create and initialize slave link for <parameter>ap</parameter>.  This enables slave
4108   link handling on the port.
4109   </para><para>
4110
4111   In libata, a port contains links and a link contains devices.
4112   There is single host link but if a PMP is attached to it,
4113   there can be multiple fan-out links.  On SATA, there's usually
4114   a single device connected to a link but PATA and SATA
4115   controllers emulating TF based interface can have two - master
4116   and slave.
4117   </para><para>
4118
4119   However, there are a few controllers which don't fit into this
4120   abstraction too well - SATA controllers which emulate TF
4121   interface with both master and slave devices but also have
4122   separate SCR register sets for each device.  These controllers
4123   need separate links for physical link handling
4124   (e.g. onlineness, link speed) but should be treated like a
4125   traditional M/S controller for everything else (e.g. command
4126   issue, softreset).
4127   </para><para>
4128
4129   slave_link is libata's way of handling this class of
4130   controllers without impacting core layer too much.  For
4131   anything other than physical link handling, the default host
4132   link is used for both master and slave.  For physical link
4133   handling, separate <parameter>ap</parameter>-&gt;slave_link is used.  All dirty details
4134   are implemented inside libata core layer.  From LLD's POV, the
4135   only difference is that prereset, hardreset and postreset are
4136   called once more for the slave link, so the reset sequence
4137   looks like the following.
4138   </para><para>
4139
4140   prereset(M) -&gt; prereset(S) -&gt; hardreset(M) -&gt; hardreset(S) -&gt;
4141   softreset(M) -&gt; postreset(M) -&gt; postreset(S)
4142   </para><para>
4143
4144   Note that softreset is called only for the master.  Softreset
4145   resets both M/S by definition, so SRST on master should handle
4146   both (the standard method will work just fine).
4147</para>
4148</refsect1>
4149<refsect1>
4150<title>LOCKING</title>
4151<para>
4152   Should be called before host is registered.
4153</para>
4154</refsect1>
4155<refsect1>
4156<title>RETURNS</title>
4157<para>
4158   0 on success, -errno on failure.
4159</para>
4160</refsect1>
4161</refentry>
4162
4163<refentry id="API-ata-host-start">
4164<refentryinfo>
4165 <title>LINUX</title>
4166 <productname>Kernel Hackers Manual</productname>
4167 <date>July 2017</date>
4168</refentryinfo>
4169<refmeta>
4170 <refentrytitle><phrase>ata_host_start</phrase></refentrytitle>
4171 <manvolnum>9</manvolnum>
4172 <refmiscinfo class="version">4.1.27</refmiscinfo>
4173</refmeta>
4174<refnamediv>
4175 <refname>ata_host_start</refname>
4176 <refpurpose>
4177     start and freeze ports of an ATA host
4178 </refpurpose>
4179</refnamediv>
4180<refsynopsisdiv>
4181 <title>Synopsis</title>
4182  <funcsynopsis><funcprototype>
4183   <funcdef>int <function>ata_host_start </function></funcdef>
4184   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
4185  </funcprototype></funcsynopsis>
4186</refsynopsisdiv>
4187<refsect1>
4188 <title>Arguments</title>
4189 <variablelist>
4190  <varlistentry>
4191   <term><parameter>host</parameter></term>
4192   <listitem>
4193    <para>
4194     ATA host to start ports for
4195    </para>
4196   </listitem>
4197  </varlistentry>
4198 </variablelist>
4199</refsect1>
4200<refsect1>
4201<title>Description</title>
4202<para>
4203   Start and then freeze ports of <parameter>host</parameter>.  Started status is
4204   recorded in host-&gt;flags, so this function can be called
4205   multiple times.  Ports are guaranteed to get started only
4206   once.  If host-&gt;ops isn't initialized yet, its set to the
4207   first non-dummy port ops.
4208</para>
4209</refsect1>
4210<refsect1>
4211<title>LOCKING</title>
4212<para>
4213   Inherited from calling layer (may sleep).
4214</para>
4215</refsect1>
4216<refsect1>
4217<title>RETURNS</title>
4218<para>
4219   0 if all ports are started successfully, -errno otherwise.
4220</para>
4221</refsect1>
4222</refentry>
4223
4224<refentry id="API-ata-host-init">
4225<refentryinfo>
4226 <title>LINUX</title>
4227 <productname>Kernel Hackers Manual</productname>
4228 <date>July 2017</date>
4229</refentryinfo>
4230<refmeta>
4231 <refentrytitle><phrase>ata_host_init</phrase></refentrytitle>
4232 <manvolnum>9</manvolnum>
4233 <refmiscinfo class="version">4.1.27</refmiscinfo>
4234</refmeta>
4235<refnamediv>
4236 <refname>ata_host_init</refname>
4237 <refpurpose>
4238     Initialize a host struct for sas (ipr, libsas)
4239 </refpurpose>
4240</refnamediv>
4241<refsynopsisdiv>
4242 <title>Synopsis</title>
4243  <funcsynopsis><funcprototype>
4244   <funcdef>void <function>ata_host_init </function></funcdef>
4245   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
4246   <paramdef>struct device * <parameter>dev</parameter></paramdef>
4247   <paramdef>struct ata_port_operations * <parameter>ops</parameter></paramdef>
4248  </funcprototype></funcsynopsis>
4249</refsynopsisdiv>
4250<refsect1>
4251 <title>Arguments</title>
4252 <variablelist>
4253  <varlistentry>
4254   <term><parameter>host</parameter></term>
4255   <listitem>
4256    <para>
4257     host to initialize
4258    </para>
4259   </listitem>
4260  </varlistentry>
4261  <varlistentry>
4262   <term><parameter>dev</parameter></term>
4263   <listitem>
4264    <para>
4265     device host is attached to
4266    </para>
4267   </listitem>
4268  </varlistentry>
4269  <varlistentry>
4270   <term><parameter>ops</parameter></term>
4271   <listitem>
4272    <para>
4273     port_ops
4274    </para>
4275   </listitem>
4276  </varlistentry>
4277 </variablelist>
4278</refsect1>
4279</refentry>
4280
4281<refentry id="API-ata-host-register">
4282<refentryinfo>
4283 <title>LINUX</title>
4284 <productname>Kernel Hackers Manual</productname>
4285 <date>July 2017</date>
4286</refentryinfo>
4287<refmeta>
4288 <refentrytitle><phrase>ata_host_register</phrase></refentrytitle>
4289 <manvolnum>9</manvolnum>
4290 <refmiscinfo class="version">4.1.27</refmiscinfo>
4291</refmeta>
4292<refnamediv>
4293 <refname>ata_host_register</refname>
4294 <refpurpose>
4295     register initialized ATA host
4296 </refpurpose>
4297</refnamediv>
4298<refsynopsisdiv>
4299 <title>Synopsis</title>
4300  <funcsynopsis><funcprototype>
4301   <funcdef>int <function>ata_host_register </function></funcdef>
4302   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
4303   <paramdef>struct scsi_host_template * <parameter>sht</parameter></paramdef>
4304  </funcprototype></funcsynopsis>
4305</refsynopsisdiv>
4306<refsect1>
4307 <title>Arguments</title>
4308 <variablelist>
4309  <varlistentry>
4310   <term><parameter>host</parameter></term>
4311   <listitem>
4312    <para>
4313     ATA host to register
4314    </para>
4315   </listitem>
4316  </varlistentry>
4317  <varlistentry>
4318   <term><parameter>sht</parameter></term>
4319   <listitem>
4320    <para>
4321     template for SCSI host
4322    </para>
4323   </listitem>
4324  </varlistentry>
4325 </variablelist>
4326</refsect1>
4327<refsect1>
4328<title>Description</title>
4329<para>
4330   Register initialized ATA host.  <parameter>host</parameter> is allocated using
4331   <function>ata_host_alloc</function> and fully initialized by LLD.  This function
4332   starts ports, registers <parameter>host</parameter> with ATA and SCSI layers and
4333   probe registered devices.
4334</para>
4335</refsect1>
4336<refsect1>
4337<title>LOCKING</title>
4338<para>
4339   Inherited from calling layer (may sleep).
4340</para>
4341</refsect1>
4342<refsect1>
4343<title>RETURNS</title>
4344<para>
4345   0 on success, -errno otherwise.
4346</para>
4347</refsect1>
4348</refentry>
4349
4350<refentry id="API-ata-host-activate">
4351<refentryinfo>
4352 <title>LINUX</title>
4353 <productname>Kernel Hackers Manual</productname>
4354 <date>July 2017</date>
4355</refentryinfo>
4356<refmeta>
4357 <refentrytitle><phrase>ata_host_activate</phrase></refentrytitle>
4358 <manvolnum>9</manvolnum>
4359 <refmiscinfo class="version">4.1.27</refmiscinfo>
4360</refmeta>
4361<refnamediv>
4362 <refname>ata_host_activate</refname>
4363 <refpurpose>
4364     start host, request IRQ and register it
4365 </refpurpose>
4366</refnamediv>
4367<refsynopsisdiv>
4368 <title>Synopsis</title>
4369  <funcsynopsis><funcprototype>
4370   <funcdef>int <function>ata_host_activate </function></funcdef>
4371   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
4372   <paramdef>int <parameter>irq</parameter></paramdef>
4373   <paramdef>irq_handler_t <parameter>irq_handler</parameter></paramdef>
4374   <paramdef>unsigned long <parameter>irq_flags</parameter></paramdef>
4375   <paramdef>struct scsi_host_template * <parameter>sht</parameter></paramdef>
4376  </funcprototype></funcsynopsis>
4377</refsynopsisdiv>
4378<refsect1>
4379 <title>Arguments</title>
4380 <variablelist>
4381  <varlistentry>
4382   <term><parameter>host</parameter></term>
4383   <listitem>
4384    <para>
4385     target ATA host
4386    </para>
4387   </listitem>
4388  </varlistentry>
4389  <varlistentry>
4390   <term><parameter>irq</parameter></term>
4391   <listitem>
4392    <para>
4393     IRQ to request
4394    </para>
4395   </listitem>
4396  </varlistentry>
4397  <varlistentry>
4398   <term><parameter>irq_handler</parameter></term>
4399   <listitem>
4400    <para>
4401     irq_handler used when requesting IRQ
4402    </para>
4403   </listitem>
4404  </varlistentry>
4405  <varlistentry>
4406   <term><parameter>irq_flags</parameter></term>
4407   <listitem>
4408    <para>
4409     irq_flags used when requesting IRQ
4410    </para>
4411   </listitem>
4412  </varlistentry>
4413  <varlistentry>
4414   <term><parameter>sht</parameter></term>
4415   <listitem>
4416    <para>
4417     scsi_host_template to use when registering the host
4418    </para>
4419   </listitem>
4420  </varlistentry>
4421 </variablelist>
4422</refsect1>
4423<refsect1>
4424<title>Description</title>
4425<para>
4426   After allocating an ATA host and initializing it, most libata
4427   LLDs perform three steps to activate the host - start host,
4428   request IRQ and register it.  This helper takes necessasry
4429   arguments and performs the three steps in one go.
4430   </para><para>
4431
4432   An invalid IRQ skips the IRQ registration and expects the host to
4433   have set polling mode on the port. In this case, <parameter>irq_handler</parameter>
4434   should be NULL.
4435</para>
4436</refsect1>
4437<refsect1>
4438<title>LOCKING</title>
4439<para>
4440   Inherited from calling layer (may sleep).
4441</para>
4442</refsect1>
4443<refsect1>
4444<title>RETURNS</title>
4445<para>
4446   0 on success, -errno otherwise.
4447</para>
4448</refsect1>
4449</refentry>
4450
4451<refentry id="API-ata-host-detach">
4452<refentryinfo>
4453 <title>LINUX</title>
4454 <productname>Kernel Hackers Manual</productname>
4455 <date>July 2017</date>
4456</refentryinfo>
4457<refmeta>
4458 <refentrytitle><phrase>ata_host_detach</phrase></refentrytitle>
4459 <manvolnum>9</manvolnum>
4460 <refmiscinfo class="version">4.1.27</refmiscinfo>
4461</refmeta>
4462<refnamediv>
4463 <refname>ata_host_detach</refname>
4464 <refpurpose>
4465     Detach all ports of an ATA host
4466 </refpurpose>
4467</refnamediv>
4468<refsynopsisdiv>
4469 <title>Synopsis</title>
4470  <funcsynopsis><funcprototype>
4471   <funcdef>void <function>ata_host_detach </function></funcdef>
4472   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
4473  </funcprototype></funcsynopsis>
4474</refsynopsisdiv>
4475<refsect1>
4476 <title>Arguments</title>
4477 <variablelist>
4478  <varlistentry>
4479   <term><parameter>host</parameter></term>
4480   <listitem>
4481    <para>
4482     Host to detach
4483    </para>
4484   </listitem>
4485  </varlistentry>
4486 </variablelist>
4487</refsect1>
4488<refsect1>
4489<title>Description</title>
4490<para>
4491   Detach all ports of <parameter>host</parameter>.
4492</para>
4493</refsect1>
4494<refsect1>
4495<title>LOCKING</title>
4496<para>
4497   Kernel thread context (may sleep).
4498</para>
4499</refsect1>
4500</refentry>
4501
4502<refentry id="API-ata-pci-remove-one">
4503<refentryinfo>
4504 <title>LINUX</title>
4505 <productname>Kernel Hackers Manual</productname>
4506 <date>July 2017</date>
4507</refentryinfo>
4508<refmeta>
4509 <refentrytitle><phrase>ata_pci_remove_one</phrase></refentrytitle>
4510 <manvolnum>9</manvolnum>
4511 <refmiscinfo class="version">4.1.27</refmiscinfo>
4512</refmeta>
4513<refnamediv>
4514 <refname>ata_pci_remove_one</refname>
4515 <refpurpose>
4516     PCI layer callback for device removal
4517 </refpurpose>
4518</refnamediv>
4519<refsynopsisdiv>
4520 <title>Synopsis</title>
4521  <funcsynopsis><funcprototype>
4522   <funcdef>void <function>ata_pci_remove_one </function></funcdef>
4523   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
4524  </funcprototype></funcsynopsis>
4525</refsynopsisdiv>
4526<refsect1>
4527 <title>Arguments</title>
4528 <variablelist>
4529  <varlistentry>
4530   <term><parameter>pdev</parameter></term>
4531   <listitem>
4532    <para>
4533     PCI device that was removed
4534    </para>
4535   </listitem>
4536  </varlistentry>
4537 </variablelist>
4538</refsect1>
4539<refsect1>
4540<title>Description</title>
4541<para>
4542   PCI layer indicates to libata via this hook that hot-unplug or
4543   module unload event has occurred.  Detach all ports.  Resource
4544   release is handled via devres.
4545</para>
4546</refsect1>
4547<refsect1>
4548<title>LOCKING</title>
4549<para>
4550   Inherited from PCI layer (may sleep).
4551</para>
4552</refsect1>
4553</refentry>
4554
4555<refentry id="API-ata-platform-remove-one">
4556<refentryinfo>
4557 <title>LINUX</title>
4558 <productname>Kernel Hackers Manual</productname>
4559 <date>July 2017</date>
4560</refentryinfo>
4561<refmeta>
4562 <refentrytitle><phrase>ata_platform_remove_one</phrase></refentrytitle>
4563 <manvolnum>9</manvolnum>
4564 <refmiscinfo class="version">4.1.27</refmiscinfo>
4565</refmeta>
4566<refnamediv>
4567 <refname>ata_platform_remove_one</refname>
4568 <refpurpose>
4569     Platform layer callback for device removal
4570 </refpurpose>
4571</refnamediv>
4572<refsynopsisdiv>
4573 <title>Synopsis</title>
4574  <funcsynopsis><funcprototype>
4575   <funcdef>int <function>ata_platform_remove_one </function></funcdef>
4576   <paramdef>struct platform_device * <parameter>pdev</parameter></paramdef>
4577  </funcprototype></funcsynopsis>
4578</refsynopsisdiv>
4579<refsect1>
4580 <title>Arguments</title>
4581 <variablelist>
4582  <varlistentry>
4583   <term><parameter>pdev</parameter></term>
4584   <listitem>
4585    <para>
4586     Platform device that was removed
4587    </para>
4588   </listitem>
4589  </varlistentry>
4590 </variablelist>
4591</refsect1>
4592<refsect1>
4593<title>Description</title>
4594<para>
4595   Platform layer indicates to libata via this hook that hot-unplug or
4596   module unload event has occurred.  Detach all ports.  Resource
4597   release is handled via devres.
4598</para>
4599</refsect1>
4600<refsect1>
4601<title>LOCKING</title>
4602<para>
4603   Inherited from platform layer (may sleep).
4604</para>
4605</refsect1>
4606</refentry>
4607
4608<refentry id="API-ata-msleep">
4609<refentryinfo>
4610 <title>LINUX</title>
4611 <productname>Kernel Hackers Manual</productname>
4612 <date>July 2017</date>
4613</refentryinfo>
4614<refmeta>
4615 <refentrytitle><phrase>ata_msleep</phrase></refentrytitle>
4616 <manvolnum>9</manvolnum>
4617 <refmiscinfo class="version">4.1.27</refmiscinfo>
4618</refmeta>
4619<refnamediv>
4620 <refname>ata_msleep</refname>
4621 <refpurpose>
4622     ATA EH owner aware msleep
4623 </refpurpose>
4624</refnamediv>
4625<refsynopsisdiv>
4626 <title>Synopsis</title>
4627  <funcsynopsis><funcprototype>
4628   <funcdef>void <function>ata_msleep </function></funcdef>
4629   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
4630   <paramdef>unsigned int <parameter>msecs</parameter></paramdef>
4631  </funcprototype></funcsynopsis>
4632</refsynopsisdiv>
4633<refsect1>
4634 <title>Arguments</title>
4635 <variablelist>
4636  <varlistentry>
4637   <term><parameter>ap</parameter></term>
4638   <listitem>
4639    <para>
4640     ATA port to attribute the sleep to
4641    </para>
4642   </listitem>
4643  </varlistentry>
4644  <varlistentry>
4645   <term><parameter>msecs</parameter></term>
4646   <listitem>
4647    <para>
4648     duration to sleep in milliseconds
4649    </para>
4650   </listitem>
4651  </varlistentry>
4652 </variablelist>
4653</refsect1>
4654<refsect1>
4655<title>Description</title>
4656<para>
4657   Sleeps <parameter>msecs</parameter>.  If the current task is owner of <parameter>ap</parameter>'s EH, the
4658   ownership is released before going to sleep and reacquired
4659   after the sleep is complete.  IOW, other ports sharing the
4660   <parameter>ap</parameter>-&gt;host will be allowed to own the EH while this task is
4661   sleeping.
4662</para>
4663</refsect1>
4664<refsect1>
4665<title>LOCKING</title>
4666<para>
4667   Might sleep.
4668</para>
4669</refsect1>
4670</refentry>
4671
4672<refentry id="API-ata-wait-register">
4673<refentryinfo>
4674 <title>LINUX</title>
4675 <productname>Kernel Hackers Manual</productname>
4676 <date>July 2017</date>
4677</refentryinfo>
4678<refmeta>
4679 <refentrytitle><phrase>ata_wait_register</phrase></refentrytitle>
4680 <manvolnum>9</manvolnum>
4681 <refmiscinfo class="version">4.1.27</refmiscinfo>
4682</refmeta>
4683<refnamediv>
4684 <refname>ata_wait_register</refname>
4685 <refpurpose>
4686     wait until register value changes
4687 </refpurpose>
4688</refnamediv>
4689<refsynopsisdiv>
4690 <title>Synopsis</title>
4691  <funcsynopsis><funcprototype>
4692   <funcdef>u32 <function>ata_wait_register </function></funcdef>
4693   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
4694   <paramdef>void __iomem * <parameter>reg</parameter></paramdef>
4695   <paramdef>u32 <parameter>mask</parameter></paramdef>
4696   <paramdef>u32 <parameter>val</parameter></paramdef>
4697   <paramdef>unsigned long <parameter>interval</parameter></paramdef>
4698   <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
4699  </funcprototype></funcsynopsis>
4700</refsynopsisdiv>
4701<refsect1>
4702 <title>Arguments</title>
4703 <variablelist>
4704  <varlistentry>
4705   <term><parameter>ap</parameter></term>
4706   <listitem>
4707    <para>
4708     ATA port to wait register for, can be NULL
4709    </para>
4710   </listitem>
4711  </varlistentry>
4712  <varlistentry>
4713   <term><parameter>reg</parameter></term>
4714   <listitem>
4715    <para>
4716     IO-mapped register
4717    </para>
4718   </listitem>
4719  </varlistentry>
4720  <varlistentry>
4721   <term><parameter>mask</parameter></term>
4722   <listitem>
4723    <para>
4724     Mask to apply to read register value
4725    </para>
4726   </listitem>
4727  </varlistentry>
4728  <varlistentry>
4729   <term><parameter>val</parameter></term>
4730   <listitem>
4731    <para>
4732     Wait condition
4733    </para>
4734   </listitem>
4735  </varlistentry>
4736  <varlistentry>
4737   <term><parameter>interval</parameter></term>
4738   <listitem>
4739    <para>
4740     polling interval in milliseconds
4741    </para>
4742   </listitem>
4743  </varlistentry>
4744  <varlistentry>
4745   <term><parameter>timeout</parameter></term>
4746   <listitem>
4747    <para>
4748     timeout in milliseconds
4749    </para>
4750   </listitem>
4751  </varlistentry>
4752 </variablelist>
4753</refsect1>
4754<refsect1>
4755<title>Description</title>
4756<para>
4757   Waiting for some bits of register to change is a common
4758   operation for ATA controllers.  This function reads 32bit LE
4759   IO-mapped register <parameter>reg</parameter> and tests for the following condition.
4760   </para><para>
4761
4762   (*<parameter>reg</parameter> &amp; mask) != val
4763   </para><para>
4764
4765   If the condition is met, it returns; otherwise, the process is
4766   repeated after <parameter>interval_msec</parameter> until timeout.
4767</para>
4768</refsect1>
4769<refsect1>
4770<title>LOCKING</title>
4771<para>
4772   Kernel thread context (may sleep)
4773</para>
4774</refsect1>
4775<refsect1>
4776<title>RETURNS</title>
4777<para>
4778   The final register value.
4779</para>
4780</refsect1>
4781</refentry>
4782
4783<refentry id="API-sata-lpm-ignore-phy-events">
4784<refentryinfo>
4785 <title>LINUX</title>
4786 <productname>Kernel Hackers Manual</productname>
4787 <date>July 2017</date>
4788</refentryinfo>
4789<refmeta>
4790 <refentrytitle><phrase>sata_lpm_ignore_phy_events</phrase></refentrytitle>
4791 <manvolnum>9</manvolnum>
4792 <refmiscinfo class="version">4.1.27</refmiscinfo>
4793</refmeta>
4794<refnamediv>
4795 <refname>sata_lpm_ignore_phy_events</refname>
4796 <refpurpose>
4797     test if PHY event should be ignored
4798 </refpurpose>
4799</refnamediv>
4800<refsynopsisdiv>
4801 <title>Synopsis</title>
4802  <funcsynopsis><funcprototype>
4803   <funcdef>bool <function>sata_lpm_ignore_phy_events </function></funcdef>
4804   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
4805  </funcprototype></funcsynopsis>
4806</refsynopsisdiv>
4807<refsect1>
4808 <title>Arguments</title>
4809 <variablelist>
4810  <varlistentry>
4811   <term><parameter>link</parameter></term>
4812   <listitem>
4813    <para>
4814     Link receiving the event
4815    </para>
4816   </listitem>
4817  </varlistentry>
4818 </variablelist>
4819</refsect1>
4820<refsect1>
4821<title>Description</title>
4822<para>
4823   Test whether the received PHY event has to be ignored or not.
4824</para>
4825</refsect1>
4826<refsect1>
4827<title>RETURNS</title>
4828<para>
4829   True if the event has to be ignored.
4830</para>
4831</refsect1>
4832</refentry>
4833
4834  </chapter>
4835
4836  <chapter id="libataInt">
4837     <title>libata Core Internals</title>
4838<!-- drivers/ata/libata-core.c -->
4839<refentry id="API-ata-dev-phys-link">
4840<refentryinfo>
4841 <title>LINUX</title>
4842 <productname>Kernel Hackers Manual</productname>
4843 <date>July 2017</date>
4844</refentryinfo>
4845<refmeta>
4846 <refentrytitle><phrase>ata_dev_phys_link</phrase></refentrytitle>
4847 <manvolnum>9</manvolnum>
4848 <refmiscinfo class="version">4.1.27</refmiscinfo>
4849</refmeta>
4850<refnamediv>
4851 <refname>ata_dev_phys_link</refname>
4852 <refpurpose>
4853  find physical link for a device
4854 </refpurpose>
4855</refnamediv>
4856<refsynopsisdiv>
4857 <title>Synopsis</title>
4858  <funcsynopsis><funcprototype>
4859   <funcdef>struct ata_link * <function>ata_dev_phys_link </function></funcdef>
4860   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
4861  </funcprototype></funcsynopsis>
4862</refsynopsisdiv>
4863<refsect1>
4864 <title>Arguments</title>
4865 <variablelist>
4866  <varlistentry>
4867   <term><parameter>dev</parameter></term>
4868   <listitem>
4869    <para>
4870     ATA device to look up physical link for
4871    </para>
4872   </listitem>
4873  </varlistentry>
4874 </variablelist>
4875</refsect1>
4876<refsect1>
4877<title>Description</title>
4878<para>
4879   Look up physical link which <parameter>dev</parameter> is attached to.  Note that
4880   this is different from <parameter>dev</parameter>-&gt;link only when <parameter>dev</parameter> is on slave
4881   link.  For all other cases, it's the same as <parameter>dev</parameter>-&gt;link.
4882</para>
4883</refsect1>
4884<refsect1>
4885<title>LOCKING</title>
4886<para>
4887   Don't care.
4888</para>
4889</refsect1>
4890<refsect1>
4891<title>RETURNS</title>
4892<para>
4893   Pointer to the found physical link.
4894</para>
4895</refsect1>
4896</refentry>
4897
4898<refentry id="API-ata-force-cbl">
4899<refentryinfo>
4900 <title>LINUX</title>
4901 <productname>Kernel Hackers Manual</productname>
4902 <date>July 2017</date>
4903</refentryinfo>
4904<refmeta>
4905 <refentrytitle><phrase>ata_force_cbl</phrase></refentrytitle>
4906 <manvolnum>9</manvolnum>
4907 <refmiscinfo class="version">4.1.27</refmiscinfo>
4908</refmeta>
4909<refnamediv>
4910 <refname>ata_force_cbl</refname>
4911 <refpurpose>
4912     force cable type according to libata.force
4913 </refpurpose>
4914</refnamediv>
4915<refsynopsisdiv>
4916 <title>Synopsis</title>
4917  <funcsynopsis><funcprototype>
4918   <funcdef>void <function>ata_force_cbl </function></funcdef>
4919   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
4920  </funcprototype></funcsynopsis>
4921</refsynopsisdiv>
4922<refsect1>
4923 <title>Arguments</title>
4924 <variablelist>
4925  <varlistentry>
4926   <term><parameter>ap</parameter></term>
4927   <listitem>
4928    <para>
4929     ATA port of interest
4930    </para>
4931   </listitem>
4932  </varlistentry>
4933 </variablelist>
4934</refsect1>
4935<refsect1>
4936<title>Description</title>
4937<para>
4938   Force cable type according to libata.force and whine about it.
4939   The last entry which has matching port number is used, so it
4940   can be specified as part of device force parameters.  For
4941   example, both <quote>a:40c,1.00:udma4</quote> and <quote>1.00:40c,udma4</quote> have the
4942   same effect.
4943</para>
4944</refsect1>
4945<refsect1>
4946<title>LOCKING</title>
4947<para>
4948   EH context.
4949</para>
4950</refsect1>
4951</refentry>
4952
4953<refentry id="API-ata-force-link-limits">
4954<refentryinfo>
4955 <title>LINUX</title>
4956 <productname>Kernel Hackers Manual</productname>
4957 <date>July 2017</date>
4958</refentryinfo>
4959<refmeta>
4960 <refentrytitle><phrase>ata_force_link_limits</phrase></refentrytitle>
4961 <manvolnum>9</manvolnum>
4962 <refmiscinfo class="version">4.1.27</refmiscinfo>
4963</refmeta>
4964<refnamediv>
4965 <refname>ata_force_link_limits</refname>
4966 <refpurpose>
4967     force link limits according to libata.force
4968 </refpurpose>
4969</refnamediv>
4970<refsynopsisdiv>
4971 <title>Synopsis</title>
4972  <funcsynopsis><funcprototype>
4973   <funcdef>void <function>ata_force_link_limits </function></funcdef>
4974   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
4975  </funcprototype></funcsynopsis>
4976</refsynopsisdiv>
4977<refsect1>
4978 <title>Arguments</title>
4979 <variablelist>
4980  <varlistentry>
4981   <term><parameter>link</parameter></term>
4982   <listitem>
4983    <para>
4984     ATA link of interest
4985    </para>
4986   </listitem>
4987  </varlistentry>
4988 </variablelist>
4989</refsect1>
4990<refsect1>
4991<title>Description</title>
4992<para>
4993   Force link flags and SATA spd limit according to libata.force
4994   and whine about it.  When only the port part is specified
4995   (e.g. 1:), the limit applies to all links connected to both
4996   the host link and all fan-out ports connected via PMP.  If the
4997   device part is specified as 0 (e.g. 1.00:), it specifies the
4998   first fan-out link not the host link.  Device number 15 always
4999   points to the host link whether PMP is attached or not.  If the
5000   controller has slave link, device number 16 points to it.
5001</para>
5002</refsect1>
5003<refsect1>
5004<title>LOCKING</title>
5005<para>
5006   EH context.
5007</para>
5008</refsect1>
5009</refentry>
5010
5011<refentry id="API-ata-force-xfermask">
5012<refentryinfo>
5013 <title>LINUX</title>
5014 <productname>Kernel Hackers Manual</productname>
5015 <date>July 2017</date>
5016</refentryinfo>
5017<refmeta>
5018 <refentrytitle><phrase>ata_force_xfermask</phrase></refentrytitle>
5019 <manvolnum>9</manvolnum>
5020 <refmiscinfo class="version">4.1.27</refmiscinfo>
5021</refmeta>
5022<refnamediv>
5023 <refname>ata_force_xfermask</refname>
5024 <refpurpose>
5025     force xfermask according to libata.force
5026 </refpurpose>
5027</refnamediv>
5028<refsynopsisdiv>
5029 <title>Synopsis</title>
5030  <funcsynopsis><funcprototype>
5031   <funcdef>void <function>ata_force_xfermask </function></funcdef>
5032   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5033  </funcprototype></funcsynopsis>
5034</refsynopsisdiv>
5035<refsect1>
5036 <title>Arguments</title>
5037 <variablelist>
5038  <varlistentry>
5039   <term><parameter>dev</parameter></term>
5040   <listitem>
5041    <para>
5042     ATA device of interest
5043    </para>
5044   </listitem>
5045  </varlistentry>
5046 </variablelist>
5047</refsect1>
5048<refsect1>
5049<title>Description</title>
5050<para>
5051   Force xfer_mask according to libata.force and whine about it.
5052   For consistency with link selection, device number 15 selects
5053   the first device connected to the host link.
5054</para>
5055</refsect1>
5056<refsect1>
5057<title>LOCKING</title>
5058<para>
5059   EH context.
5060</para>
5061</refsect1>
5062</refentry>
5063
5064<refentry id="API-ata-force-horkage">
5065<refentryinfo>
5066 <title>LINUX</title>
5067 <productname>Kernel Hackers Manual</productname>
5068 <date>July 2017</date>
5069</refentryinfo>
5070<refmeta>
5071 <refentrytitle><phrase>ata_force_horkage</phrase></refentrytitle>
5072 <manvolnum>9</manvolnum>
5073 <refmiscinfo class="version">4.1.27</refmiscinfo>
5074</refmeta>
5075<refnamediv>
5076 <refname>ata_force_horkage</refname>
5077 <refpurpose>
5078     force horkage according to libata.force
5079 </refpurpose>
5080</refnamediv>
5081<refsynopsisdiv>
5082 <title>Synopsis</title>
5083  <funcsynopsis><funcprototype>
5084   <funcdef>void <function>ata_force_horkage </function></funcdef>
5085   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5086  </funcprototype></funcsynopsis>
5087</refsynopsisdiv>
5088<refsect1>
5089 <title>Arguments</title>
5090 <variablelist>
5091  <varlistentry>
5092   <term><parameter>dev</parameter></term>
5093   <listitem>
5094    <para>
5095     ATA device of interest
5096    </para>
5097   </listitem>
5098  </varlistentry>
5099 </variablelist>
5100</refsect1>
5101<refsect1>
5102<title>Description</title>
5103<para>
5104   Force horkage according to libata.force and whine about it.
5105   For consistency with link selection, device number 15 selects
5106   the first device connected to the host link.
5107</para>
5108</refsect1>
5109<refsect1>
5110<title>LOCKING</title>
5111<para>
5112   EH context.
5113</para>
5114</refsect1>
5115</refentry>
5116
5117<refentry id="API-ata-rwcmd-protocol">
5118<refentryinfo>
5119 <title>LINUX</title>
5120 <productname>Kernel Hackers Manual</productname>
5121 <date>July 2017</date>
5122</refentryinfo>
5123<refmeta>
5124 <refentrytitle><phrase>ata_rwcmd_protocol</phrase></refentrytitle>
5125 <manvolnum>9</manvolnum>
5126 <refmiscinfo class="version">4.1.27</refmiscinfo>
5127</refmeta>
5128<refnamediv>
5129 <refname>ata_rwcmd_protocol</refname>
5130 <refpurpose>
5131     set taskfile r/w commands and protocol
5132 </refpurpose>
5133</refnamediv>
5134<refsynopsisdiv>
5135 <title>Synopsis</title>
5136  <funcsynopsis><funcprototype>
5137   <funcdef>int <function>ata_rwcmd_protocol </function></funcdef>
5138   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
5139   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5140  </funcprototype></funcsynopsis>
5141</refsynopsisdiv>
5142<refsect1>
5143 <title>Arguments</title>
5144 <variablelist>
5145  <varlistentry>
5146   <term><parameter>tf</parameter></term>
5147   <listitem>
5148    <para>
5149     command to examine and configure
5150    </para>
5151   </listitem>
5152  </varlistentry>
5153  <varlistentry>
5154   <term><parameter>dev</parameter></term>
5155   <listitem>
5156    <para>
5157     device tf belongs to
5158    </para>
5159   </listitem>
5160  </varlistentry>
5161 </variablelist>
5162</refsect1>
5163<refsect1>
5164<title>Description</title>
5165<para>
5166   Examine the device configuration and tf-&gt;flags to calculate
5167   the proper read/write commands and protocol to use.
5168</para>
5169</refsect1>
5170<refsect1>
5171<title>LOCKING</title>
5172<para>
5173   caller.
5174</para>
5175</refsect1>
5176</refentry>
5177
5178<refentry id="API-ata-tf-read-block">
5179<refentryinfo>
5180 <title>LINUX</title>
5181 <productname>Kernel Hackers Manual</productname>
5182 <date>July 2017</date>
5183</refentryinfo>
5184<refmeta>
5185 <refentrytitle><phrase>ata_tf_read_block</phrase></refentrytitle>
5186 <manvolnum>9</manvolnum>
5187 <refmiscinfo class="version">4.1.27</refmiscinfo>
5188</refmeta>
5189<refnamediv>
5190 <refname>ata_tf_read_block</refname>
5191 <refpurpose>
5192     Read block address from ATA taskfile
5193 </refpurpose>
5194</refnamediv>
5195<refsynopsisdiv>
5196 <title>Synopsis</title>
5197  <funcsynopsis><funcprototype>
5198   <funcdef>u64 <function>ata_tf_read_block </function></funcdef>
5199   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
5200   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5201  </funcprototype></funcsynopsis>
5202</refsynopsisdiv>
5203<refsect1>
5204 <title>Arguments</title>
5205 <variablelist>
5206  <varlistentry>
5207   <term><parameter>tf</parameter></term>
5208   <listitem>
5209    <para>
5210     ATA taskfile of interest
5211    </para>
5212   </listitem>
5213  </varlistentry>
5214  <varlistentry>
5215   <term><parameter>dev</parameter></term>
5216   <listitem>
5217    <para>
5218     ATA device <parameter>tf</parameter> belongs to
5219    </para>
5220   </listitem>
5221  </varlistentry>
5222 </variablelist>
5223</refsect1>
5224<refsect1>
5225<title>LOCKING</title>
5226<para>
5227   None.
5228   </para><para>
5229
5230   Read block address from <parameter>tf</parameter>.  This function can handle all
5231   three address formats - LBA, LBA48 and CHS.  tf-&gt;protocol and
5232   flags select the address format to use.
5233</para>
5234</refsect1>
5235<refsect1>
5236<title>RETURNS</title>
5237<para>
5238   Block address read from <parameter>tf</parameter>.
5239</para>
5240</refsect1>
5241</refentry>
5242
5243<refentry id="API-ata-build-rw-tf">
5244<refentryinfo>
5245 <title>LINUX</title>
5246 <productname>Kernel Hackers Manual</productname>
5247 <date>July 2017</date>
5248</refentryinfo>
5249<refmeta>
5250 <refentrytitle><phrase>ata_build_rw_tf</phrase></refentrytitle>
5251 <manvolnum>9</manvolnum>
5252 <refmiscinfo class="version">4.1.27</refmiscinfo>
5253</refmeta>
5254<refnamediv>
5255 <refname>ata_build_rw_tf</refname>
5256 <refpurpose>
5257     Build ATA taskfile for given read/write request
5258 </refpurpose>
5259</refnamediv>
5260<refsynopsisdiv>
5261 <title>Synopsis</title>
5262  <funcsynopsis><funcprototype>
5263   <funcdef>int <function>ata_build_rw_tf </function></funcdef>
5264   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
5265   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5266   <paramdef>u64 <parameter>block</parameter></paramdef>
5267   <paramdef>u32 <parameter>n_block</parameter></paramdef>
5268   <paramdef>unsigned int <parameter>tf_flags</parameter></paramdef>
5269   <paramdef>unsigned int <parameter>tag</parameter></paramdef>
5270  </funcprototype></funcsynopsis>
5271</refsynopsisdiv>
5272<refsect1>
5273 <title>Arguments</title>
5274 <variablelist>
5275  <varlistentry>
5276   <term><parameter>tf</parameter></term>
5277   <listitem>
5278    <para>
5279     Target ATA taskfile
5280    </para>
5281   </listitem>
5282  </varlistentry>
5283  <varlistentry>
5284   <term><parameter>dev</parameter></term>
5285   <listitem>
5286    <para>
5287     ATA device <parameter>tf</parameter> belongs to
5288    </para>
5289   </listitem>
5290  </varlistentry>
5291  <varlistentry>
5292   <term><parameter>block</parameter></term>
5293   <listitem>
5294    <para>
5295     Block address
5296    </para>
5297   </listitem>
5298  </varlistentry>
5299  <varlistentry>
5300   <term><parameter>n_block</parameter></term>
5301   <listitem>
5302    <para>
5303     Number of blocks
5304    </para>
5305   </listitem>
5306  </varlistentry>
5307  <varlistentry>
5308   <term><parameter>tf_flags</parameter></term>
5309   <listitem>
5310    <para>
5311     RW/FUA etc...
5312    </para>
5313   </listitem>
5314  </varlistentry>
5315  <varlistentry>
5316   <term><parameter>tag</parameter></term>
5317   <listitem>
5318    <para>
5319     tag
5320    </para>
5321   </listitem>
5322  </varlistentry>
5323 </variablelist>
5324</refsect1>
5325<refsect1>
5326<title>LOCKING</title>
5327<para>
5328   None.
5329   </para><para>
5330
5331   Build ATA taskfile <parameter>tf</parameter> for read/write request described by
5332   <parameter>block</parameter>, <parameter>n_block</parameter>, <parameter>tf_flags</parameter> and <parameter>tag</parameter> on <parameter>dev</parameter>.
5333</para>
5334</refsect1>
5335<refsect1>
5336<title>RETURNS</title>
5337<para>
5338   </para><para>
5339
5340   0 on success, -ERANGE if the request is too large for <parameter>dev</parameter>,
5341   -EINVAL if the request is invalid.
5342</para>
5343</refsect1>
5344</refentry>
5345
5346<refentry id="API-ata-read-native-max-address">
5347<refentryinfo>
5348 <title>LINUX</title>
5349 <productname>Kernel Hackers Manual</productname>
5350 <date>July 2017</date>
5351</refentryinfo>
5352<refmeta>
5353 <refentrytitle><phrase>ata_read_native_max_address</phrase></refentrytitle>
5354 <manvolnum>9</manvolnum>
5355 <refmiscinfo class="version">4.1.27</refmiscinfo>
5356</refmeta>
5357<refnamediv>
5358 <refname>ata_read_native_max_address</refname>
5359 <refpurpose>
5360     Read native max address
5361 </refpurpose>
5362</refnamediv>
5363<refsynopsisdiv>
5364 <title>Synopsis</title>
5365  <funcsynopsis><funcprototype>
5366   <funcdef>int <function>ata_read_native_max_address </function></funcdef>
5367   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5368   <paramdef>u64 * <parameter>max_sectors</parameter></paramdef>
5369  </funcprototype></funcsynopsis>
5370</refsynopsisdiv>
5371<refsect1>
5372 <title>Arguments</title>
5373 <variablelist>
5374  <varlistentry>
5375   <term><parameter>dev</parameter></term>
5376   <listitem>
5377    <para>
5378     target device
5379    </para>
5380   </listitem>
5381  </varlistentry>
5382  <varlistentry>
5383   <term><parameter>max_sectors</parameter></term>
5384   <listitem>
5385    <para>
5386     out parameter for the result native max address
5387    </para>
5388   </listitem>
5389  </varlistentry>
5390 </variablelist>
5391</refsect1>
5392<refsect1>
5393<title>Description</title>
5394<para>
5395   Perform an LBA48 or LBA28 native size query upon the device in
5396   question.
5397</para>
5398</refsect1>
5399<refsect1>
5400<title>RETURNS</title>
5401<para>
5402   0 on success, -EACCES if command is aborted by the drive.
5403   -EIO on other errors.
5404</para>
5405</refsect1>
5406</refentry>
5407
5408<refentry id="API-ata-set-max-sectors">
5409<refentryinfo>
5410 <title>LINUX</title>
5411 <productname>Kernel Hackers Manual</productname>
5412 <date>July 2017</date>
5413</refentryinfo>
5414<refmeta>
5415 <refentrytitle><phrase>ata_set_max_sectors</phrase></refentrytitle>
5416 <manvolnum>9</manvolnum>
5417 <refmiscinfo class="version">4.1.27</refmiscinfo>
5418</refmeta>
5419<refnamediv>
5420 <refname>ata_set_max_sectors</refname>
5421 <refpurpose>
5422     Set max sectors
5423 </refpurpose>
5424</refnamediv>
5425<refsynopsisdiv>
5426 <title>Synopsis</title>
5427  <funcsynopsis><funcprototype>
5428   <funcdef>int <function>ata_set_max_sectors </function></funcdef>
5429   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5430   <paramdef>u64 <parameter>new_sectors</parameter></paramdef>
5431  </funcprototype></funcsynopsis>
5432</refsynopsisdiv>
5433<refsect1>
5434 <title>Arguments</title>
5435 <variablelist>
5436  <varlistentry>
5437   <term><parameter>dev</parameter></term>
5438   <listitem>
5439    <para>
5440     target device
5441    </para>
5442   </listitem>
5443  </varlistentry>
5444  <varlistentry>
5445   <term><parameter>new_sectors</parameter></term>
5446   <listitem>
5447    <para>
5448     new max sectors value to set for the device
5449    </para>
5450   </listitem>
5451  </varlistentry>
5452 </variablelist>
5453</refsect1>
5454<refsect1>
5455<title>Description</title>
5456<para>
5457   Set max sectors of <parameter>dev</parameter> to <parameter>new_sectors</parameter>.
5458</para>
5459</refsect1>
5460<refsect1>
5461<title>RETURNS</title>
5462<para>
5463   0 on success, -EACCES if command is aborted or denied (due to
5464   previous non-volatile SET_MAX) by the drive.  -EIO on other
5465   errors.
5466</para>
5467</refsect1>
5468</refentry>
5469
5470<refentry id="API-ata-hpa-resize">
5471<refentryinfo>
5472 <title>LINUX</title>
5473 <productname>Kernel Hackers Manual</productname>
5474 <date>July 2017</date>
5475</refentryinfo>
5476<refmeta>
5477 <refentrytitle><phrase>ata_hpa_resize</phrase></refentrytitle>
5478 <manvolnum>9</manvolnum>
5479 <refmiscinfo class="version">4.1.27</refmiscinfo>
5480</refmeta>
5481<refnamediv>
5482 <refname>ata_hpa_resize</refname>
5483 <refpurpose>
5484     Resize a device with an HPA set
5485 </refpurpose>
5486</refnamediv>
5487<refsynopsisdiv>
5488 <title>Synopsis</title>
5489  <funcsynopsis><funcprototype>
5490   <funcdef>int <function>ata_hpa_resize </function></funcdef>
5491   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5492  </funcprototype></funcsynopsis>
5493</refsynopsisdiv>
5494<refsect1>
5495 <title>Arguments</title>
5496 <variablelist>
5497  <varlistentry>
5498   <term><parameter>dev</parameter></term>
5499   <listitem>
5500    <para>
5501     Device to resize
5502    </para>
5503   </listitem>
5504  </varlistentry>
5505 </variablelist>
5506</refsect1>
5507<refsect1>
5508<title>Description</title>
5509<para>
5510   Read the size of an LBA28 or LBA48 disk with HPA features and resize
5511   it if required to the full size of the media. The caller must check
5512   the drive has the HPA feature set enabled.
5513</para>
5514</refsect1>
5515<refsect1>
5516<title>RETURNS</title>
5517<para>
5518   0 on success, -errno on failure.
5519</para>
5520</refsect1>
5521</refentry>
5522
5523<refentry id="API-ata-dump-id">
5524<refentryinfo>
5525 <title>LINUX</title>
5526 <productname>Kernel Hackers Manual</productname>
5527 <date>July 2017</date>
5528</refentryinfo>
5529<refmeta>
5530 <refentrytitle><phrase>ata_dump_id</phrase></refentrytitle>
5531 <manvolnum>9</manvolnum>
5532 <refmiscinfo class="version">4.1.27</refmiscinfo>
5533</refmeta>
5534<refnamediv>
5535 <refname>ata_dump_id</refname>
5536 <refpurpose>
5537     IDENTIFY DEVICE info debugging output
5538 </refpurpose>
5539</refnamediv>
5540<refsynopsisdiv>
5541 <title>Synopsis</title>
5542  <funcsynopsis><funcprototype>
5543   <funcdef>void <function>ata_dump_id </function></funcdef>
5544   <paramdef>const u16 * <parameter>id</parameter></paramdef>
5545  </funcprototype></funcsynopsis>
5546</refsynopsisdiv>
5547<refsect1>
5548 <title>Arguments</title>
5549 <variablelist>
5550  <varlistentry>
5551   <term><parameter>id</parameter></term>
5552   <listitem>
5553    <para>
5554     IDENTIFY DEVICE page to dump
5555    </para>
5556   </listitem>
5557  </varlistentry>
5558 </variablelist>
5559</refsect1>
5560<refsect1>
5561<title>Description</title>
5562<para>
5563   Dump selected 16-bit words from the given IDENTIFY DEVICE
5564   page.
5565</para>
5566</refsect1>
5567<refsect1>
5568<title>LOCKING</title>
5569<para>
5570   caller.
5571</para>
5572</refsect1>
5573</refentry>
5574
5575<refentry id="API-ata-exec-internal-sg">
5576<refentryinfo>
5577 <title>LINUX</title>
5578 <productname>Kernel Hackers Manual</productname>
5579 <date>July 2017</date>
5580</refentryinfo>
5581<refmeta>
5582 <refentrytitle><phrase>ata_exec_internal_sg</phrase></refentrytitle>
5583 <manvolnum>9</manvolnum>
5584 <refmiscinfo class="version">4.1.27</refmiscinfo>
5585</refmeta>
5586<refnamediv>
5587 <refname>ata_exec_internal_sg</refname>
5588 <refpurpose>
5589     execute libata internal command
5590 </refpurpose>
5591</refnamediv>
5592<refsynopsisdiv>
5593 <title>Synopsis</title>
5594  <funcsynopsis><funcprototype>
5595   <funcdef>unsigned <function>ata_exec_internal_sg </function></funcdef>
5596   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5597   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
5598   <paramdef>const u8 * <parameter>cdb</parameter></paramdef>
5599   <paramdef>int <parameter>dma_dir</parameter></paramdef>
5600   <paramdef>struct scatterlist * <parameter>sgl</parameter></paramdef>
5601   <paramdef>unsigned int <parameter>n_elem</parameter></paramdef>
5602   <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
5603  </funcprototype></funcsynopsis>
5604</refsynopsisdiv>
5605<refsect1>
5606 <title>Arguments</title>
5607 <variablelist>
5608  <varlistentry>
5609   <term><parameter>dev</parameter></term>
5610   <listitem>
5611    <para>
5612     Device to which the command is sent
5613    </para>
5614   </listitem>
5615  </varlistentry>
5616  <varlistentry>
5617   <term><parameter>tf</parameter></term>
5618   <listitem>
5619    <para>
5620     Taskfile registers for the command and the result
5621    </para>
5622   </listitem>
5623  </varlistentry>
5624  <varlistentry>
5625   <term><parameter>cdb</parameter></term>
5626   <listitem>
5627    <para>
5628     CDB for packet command
5629    </para>
5630   </listitem>
5631  </varlistentry>
5632  <varlistentry>
5633   <term><parameter>dma_dir</parameter></term>
5634   <listitem>
5635    <para>
5636     Data transfer direction of the command
5637    </para>
5638   </listitem>
5639  </varlistentry>
5640  <varlistentry>
5641   <term><parameter>sgl</parameter></term>
5642   <listitem>
5643    <para>
5644     sg list for the data buffer of the command
5645    </para>
5646   </listitem>
5647  </varlistentry>
5648  <varlistentry>
5649   <term><parameter>n_elem</parameter></term>
5650   <listitem>
5651    <para>
5652     Number of sg entries
5653    </para>
5654   </listitem>
5655  </varlistentry>
5656  <varlistentry>
5657   <term><parameter>timeout</parameter></term>
5658   <listitem>
5659    <para>
5660     Timeout in msecs (0 for default)
5661    </para>
5662   </listitem>
5663  </varlistentry>
5664 </variablelist>
5665</refsect1>
5666<refsect1>
5667<title>Description</title>
5668<para>
5669   Executes libata internal command with timeout.  <parameter>tf</parameter> contains
5670   command on entry and result on return.  Timeout and error
5671   conditions are reported via return value.  No recovery action
5672   is taken after a command times out.  It's caller's duty to
5673   clean up after timeout.
5674</para>
5675</refsect1>
5676<refsect1>
5677<title>LOCKING</title>
5678<para>
5679   None.  Should be called with kernel context, might sleep.
5680</para>
5681</refsect1>
5682<refsect1>
5683<title>RETURNS</title>
5684<para>
5685   Zero on success, AC_ERR_* mask on failure
5686</para>
5687</refsect1>
5688</refentry>
5689
5690<refentry id="API-ata-exec-internal">
5691<refentryinfo>
5692 <title>LINUX</title>
5693 <productname>Kernel Hackers Manual</productname>
5694 <date>July 2017</date>
5695</refentryinfo>
5696<refmeta>
5697 <refentrytitle><phrase>ata_exec_internal</phrase></refentrytitle>
5698 <manvolnum>9</manvolnum>
5699 <refmiscinfo class="version">4.1.27</refmiscinfo>
5700</refmeta>
5701<refnamediv>
5702 <refname>ata_exec_internal</refname>
5703 <refpurpose>
5704     execute libata internal command
5705 </refpurpose>
5706</refnamediv>
5707<refsynopsisdiv>
5708 <title>Synopsis</title>
5709  <funcsynopsis><funcprototype>
5710   <funcdef>unsigned <function>ata_exec_internal </function></funcdef>
5711   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5712   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
5713   <paramdef>const u8 * <parameter>cdb</parameter></paramdef>
5714   <paramdef>int <parameter>dma_dir</parameter></paramdef>
5715   <paramdef>void * <parameter>buf</parameter></paramdef>
5716   <paramdef>unsigned int <parameter>buflen</parameter></paramdef>
5717   <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
5718  </funcprototype></funcsynopsis>
5719</refsynopsisdiv>
5720<refsect1>
5721 <title>Arguments</title>
5722 <variablelist>
5723  <varlistentry>
5724   <term><parameter>dev</parameter></term>
5725   <listitem>
5726    <para>
5727     Device to which the command is sent
5728    </para>
5729   </listitem>
5730  </varlistentry>
5731  <varlistentry>
5732   <term><parameter>tf</parameter></term>
5733   <listitem>
5734    <para>
5735     Taskfile registers for the command and the result
5736    </para>
5737   </listitem>
5738  </varlistentry>
5739  <varlistentry>
5740   <term><parameter>cdb</parameter></term>
5741   <listitem>
5742    <para>
5743     CDB for packet command
5744    </para>
5745   </listitem>
5746  </varlistentry>
5747  <varlistentry>
5748   <term><parameter>dma_dir</parameter></term>
5749   <listitem>
5750    <para>
5751     Data transfer direction of the command
5752    </para>
5753   </listitem>
5754  </varlistentry>
5755  <varlistentry>
5756   <term><parameter>buf</parameter></term>
5757   <listitem>
5758    <para>
5759     Data buffer of the command
5760    </para>
5761   </listitem>
5762  </varlistentry>
5763  <varlistentry>
5764   <term><parameter>buflen</parameter></term>
5765   <listitem>
5766    <para>
5767     Length of data buffer
5768    </para>
5769   </listitem>
5770  </varlistentry>
5771  <varlistentry>
5772   <term><parameter>timeout</parameter></term>
5773   <listitem>
5774    <para>
5775     Timeout in msecs (0 for default)
5776    </para>
5777   </listitem>
5778  </varlistentry>
5779 </variablelist>
5780</refsect1>
5781<refsect1>
5782<title>Description</title>
5783<para>
5784   Wrapper around <function>ata_exec_internal_sg</function> which takes simple
5785   buffer instead of sg list.
5786</para>
5787</refsect1>
5788<refsect1>
5789<title>LOCKING</title>
5790<para>
5791   None.  Should be called with kernel context, might sleep.
5792</para>
5793</refsect1>
5794<refsect1>
5795<title>RETURNS</title>
5796<para>
5797   Zero on success, AC_ERR_* mask on failure
5798</para>
5799</refsect1>
5800</refentry>
5801
5802<refentry id="API-ata-pio-mask-no-iordy">
5803<refentryinfo>
5804 <title>LINUX</title>
5805 <productname>Kernel Hackers Manual</productname>
5806 <date>July 2017</date>
5807</refentryinfo>
5808<refmeta>
5809 <refentrytitle><phrase>ata_pio_mask_no_iordy</phrase></refentrytitle>
5810 <manvolnum>9</manvolnum>
5811 <refmiscinfo class="version">4.1.27</refmiscinfo>
5812</refmeta>
5813<refnamediv>
5814 <refname>ata_pio_mask_no_iordy</refname>
5815 <refpurpose>
5816     Return the non IORDY mask
5817 </refpurpose>
5818</refnamediv>
5819<refsynopsisdiv>
5820 <title>Synopsis</title>
5821  <funcsynopsis><funcprototype>
5822   <funcdef>u32 <function>ata_pio_mask_no_iordy </function></funcdef>
5823   <paramdef>const struct ata_device * <parameter>adev</parameter></paramdef>
5824  </funcprototype></funcsynopsis>
5825</refsynopsisdiv>
5826<refsect1>
5827 <title>Arguments</title>
5828 <variablelist>
5829  <varlistentry>
5830   <term><parameter>adev</parameter></term>
5831   <listitem>
5832    <para>
5833     ATA device
5834    </para>
5835   </listitem>
5836  </varlistentry>
5837 </variablelist>
5838</refsect1>
5839<refsect1>
5840<title>Description</title>
5841<para>
5842   Compute the highest mode possible if we are not using iordy. Return
5843   -1 if no iordy mode is available.
5844</para>
5845</refsect1>
5846</refentry>
5847
5848<refentry id="API-ata-dev-read-id">
5849<refentryinfo>
5850 <title>LINUX</title>
5851 <productname>Kernel Hackers Manual</productname>
5852 <date>July 2017</date>
5853</refentryinfo>
5854<refmeta>
5855 <refentrytitle><phrase>ata_dev_read_id</phrase></refentrytitle>
5856 <manvolnum>9</manvolnum>
5857 <refmiscinfo class="version">4.1.27</refmiscinfo>
5858</refmeta>
5859<refnamediv>
5860 <refname>ata_dev_read_id</refname>
5861 <refpurpose>
5862     Read ID data from the specified device
5863 </refpurpose>
5864</refnamediv>
5865<refsynopsisdiv>
5866 <title>Synopsis</title>
5867  <funcsynopsis><funcprototype>
5868   <funcdef>int <function>ata_dev_read_id </function></funcdef>
5869   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5870   <paramdef>unsigned int * <parameter>p_class</parameter></paramdef>
5871   <paramdef>unsigned int <parameter>flags</parameter></paramdef>
5872   <paramdef>u16 * <parameter>id</parameter></paramdef>
5873  </funcprototype></funcsynopsis>
5874</refsynopsisdiv>
5875<refsect1>
5876 <title>Arguments</title>
5877 <variablelist>
5878  <varlistentry>
5879   <term><parameter>dev</parameter></term>
5880   <listitem>
5881    <para>
5882     target device
5883    </para>
5884   </listitem>
5885  </varlistentry>
5886  <varlistentry>
5887   <term><parameter>p_class</parameter></term>
5888   <listitem>
5889    <para>
5890     pointer to class of the target device (may be changed)
5891    </para>
5892   </listitem>
5893  </varlistentry>
5894  <varlistentry>
5895   <term><parameter>flags</parameter></term>
5896   <listitem>
5897    <para>
5898     ATA_READID_* flags
5899    </para>
5900   </listitem>
5901  </varlistentry>
5902  <varlistentry>
5903   <term><parameter>id</parameter></term>
5904   <listitem>
5905    <para>
5906     buffer to read IDENTIFY data into
5907    </para>
5908   </listitem>
5909  </varlistentry>
5910 </variablelist>
5911</refsect1>
5912<refsect1>
5913<title>Description</title>
5914<para>
5915   Read ID data from the specified device.  ATA_CMD_ID_ATA is
5916   performed on ATA devices and ATA_CMD_ID_ATAPI on ATAPI
5917   devices.  This function also issues ATA_CMD_INIT_DEV_PARAMS
5918   for pre-ATA4 drives.
5919</para>
5920</refsect1>
5921<refsect1>
5922<title>FIXME</title>
5923<para>
5924   ATA_CMD_ID_ATA is optional for early drives and right
5925   now we abort if we hit that case.
5926</para>
5927</refsect1>
5928<refsect1>
5929<title>LOCKING</title>
5930<para>
5931   Kernel thread context (may sleep)
5932</para>
5933</refsect1>
5934<refsect1>
5935<title>RETURNS</title>
5936<para>
5937   0 on success, -errno otherwise.
5938</para>
5939</refsect1>
5940</refentry>
5941
5942<refentry id="API-ata-dev-configure">
5943<refentryinfo>
5944 <title>LINUX</title>
5945 <productname>Kernel Hackers Manual</productname>
5946 <date>July 2017</date>
5947</refentryinfo>
5948<refmeta>
5949 <refentrytitle><phrase>ata_dev_configure</phrase></refentrytitle>
5950 <manvolnum>9</manvolnum>
5951 <refmiscinfo class="version">4.1.27</refmiscinfo>
5952</refmeta>
5953<refnamediv>
5954 <refname>ata_dev_configure</refname>
5955 <refpurpose>
5956     Configure the specified ATA/ATAPI device
5957 </refpurpose>
5958</refnamediv>
5959<refsynopsisdiv>
5960 <title>Synopsis</title>
5961  <funcsynopsis><funcprototype>
5962   <funcdef>int <function>ata_dev_configure </function></funcdef>
5963   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
5964  </funcprototype></funcsynopsis>
5965</refsynopsisdiv>
5966<refsect1>
5967 <title>Arguments</title>
5968 <variablelist>
5969  <varlistentry>
5970   <term><parameter>dev</parameter></term>
5971   <listitem>
5972    <para>
5973     Target device to configure
5974    </para>
5975   </listitem>
5976  </varlistentry>
5977 </variablelist>
5978</refsect1>
5979<refsect1>
5980<title>Description</title>
5981<para>
5982   Configure <parameter>dev</parameter> according to <parameter>dev</parameter>-&gt;id.  Generic and low-level
5983   driver specific fixups are also applied.
5984</para>
5985</refsect1>
5986<refsect1>
5987<title>LOCKING</title>
5988<para>
5989   Kernel thread context (may sleep)
5990</para>
5991</refsect1>
5992<refsect1>
5993<title>RETURNS</title>
5994<para>
5995   0 on success, -errno otherwise
5996</para>
5997</refsect1>
5998</refentry>
5999
6000<refentry id="API-ata-bus-probe">
6001<refentryinfo>
6002 <title>LINUX</title>
6003 <productname>Kernel Hackers Manual</productname>
6004 <date>July 2017</date>
6005</refentryinfo>
6006<refmeta>
6007 <refentrytitle><phrase>ata_bus_probe</phrase></refentrytitle>
6008 <manvolnum>9</manvolnum>
6009 <refmiscinfo class="version">4.1.27</refmiscinfo>
6010</refmeta>
6011<refnamediv>
6012 <refname>ata_bus_probe</refname>
6013 <refpurpose>
6014     Reset and probe ATA bus
6015 </refpurpose>
6016</refnamediv>
6017<refsynopsisdiv>
6018 <title>Synopsis</title>
6019  <funcsynopsis><funcprototype>
6020   <funcdef>int <function>ata_bus_probe </function></funcdef>
6021   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
6022  </funcprototype></funcsynopsis>
6023</refsynopsisdiv>
6024<refsect1>
6025 <title>Arguments</title>
6026 <variablelist>
6027  <varlistentry>
6028   <term><parameter>ap</parameter></term>
6029   <listitem>
6030    <para>
6031     Bus to probe
6032    </para>
6033   </listitem>
6034  </varlistentry>
6035 </variablelist>
6036</refsect1>
6037<refsect1>
6038<title>Description</title>
6039<para>
6040   Master ATA bus probing function.  Initiates a hardware-dependent
6041   bus reset, then attempts to identify any devices found on
6042   the bus.
6043</para>
6044</refsect1>
6045<refsect1>
6046<title>LOCKING</title>
6047<para>
6048   PCI/etc. bus probe sem.
6049</para>
6050</refsect1>
6051<refsect1>
6052<title>RETURNS</title>
6053<para>
6054   Zero on success, negative errno otherwise.
6055</para>
6056</refsect1>
6057</refentry>
6058
6059<refentry id="API-sata-print-link-status">
6060<refentryinfo>
6061 <title>LINUX</title>
6062 <productname>Kernel Hackers Manual</productname>
6063 <date>July 2017</date>
6064</refentryinfo>
6065<refmeta>
6066 <refentrytitle><phrase>sata_print_link_status</phrase></refentrytitle>
6067 <manvolnum>9</manvolnum>
6068 <refmiscinfo class="version">4.1.27</refmiscinfo>
6069</refmeta>
6070<refnamediv>
6071 <refname>sata_print_link_status</refname>
6072 <refpurpose>
6073     Print SATA link status
6074 </refpurpose>
6075</refnamediv>
6076<refsynopsisdiv>
6077 <title>Synopsis</title>
6078  <funcsynopsis><funcprototype>
6079   <funcdef>void <function>sata_print_link_status </function></funcdef>
6080   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
6081  </funcprototype></funcsynopsis>
6082</refsynopsisdiv>
6083<refsect1>
6084 <title>Arguments</title>
6085 <variablelist>
6086  <varlistentry>
6087   <term><parameter>link</parameter></term>
6088   <listitem>
6089    <para>
6090     SATA link to printk link status about
6091    </para>
6092   </listitem>
6093  </varlistentry>
6094 </variablelist>
6095</refsect1>
6096<refsect1>
6097<title>Description</title>
6098<para>
6099   This function prints link speed and status of a SATA link.
6100</para>
6101</refsect1>
6102<refsect1>
6103<title>LOCKING</title>
6104<para>
6105   None.
6106</para>
6107</refsect1>
6108</refentry>
6109
6110<refentry id="API-sata-down-spd-limit">
6111<refentryinfo>
6112 <title>LINUX</title>
6113 <productname>Kernel Hackers Manual</productname>
6114 <date>July 2017</date>
6115</refentryinfo>
6116<refmeta>
6117 <refentrytitle><phrase>sata_down_spd_limit</phrase></refentrytitle>
6118 <manvolnum>9</manvolnum>
6119 <refmiscinfo class="version">4.1.27</refmiscinfo>
6120</refmeta>
6121<refnamediv>
6122 <refname>sata_down_spd_limit</refname>
6123 <refpurpose>
6124     adjust SATA spd limit downward
6125 </refpurpose>
6126</refnamediv>
6127<refsynopsisdiv>
6128 <title>Synopsis</title>
6129  <funcsynopsis><funcprototype>
6130   <funcdef>int <function>sata_down_spd_limit </function></funcdef>
6131   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
6132   <paramdef>u32 <parameter>spd_limit</parameter></paramdef>
6133  </funcprototype></funcsynopsis>
6134</refsynopsisdiv>
6135<refsect1>
6136 <title>Arguments</title>
6137 <variablelist>
6138  <varlistentry>
6139   <term><parameter>link</parameter></term>
6140   <listitem>
6141    <para>
6142     Link to adjust SATA spd limit for
6143    </para>
6144   </listitem>
6145  </varlistentry>
6146  <varlistentry>
6147   <term><parameter>spd_limit</parameter></term>
6148   <listitem>
6149    <para>
6150     Additional limit
6151    </para>
6152   </listitem>
6153  </varlistentry>
6154 </variablelist>
6155</refsect1>
6156<refsect1>
6157<title>Description</title>
6158<para>
6159   Adjust SATA spd limit of <parameter>link</parameter> downward.  Note that this
6160   function only adjusts the limit.  The change must be applied
6161   using <function>sata_set_spd</function>.
6162   </para><para>
6163
6164   If <parameter>spd_limit</parameter> is non-zero, the speed is limited to equal to or
6165   lower than <parameter>spd_limit</parameter> if such speed is supported.  If
6166   <parameter>spd_limit</parameter> is slower than any supported speed, only the lowest
6167   supported speed is allowed.
6168</para>
6169</refsect1>
6170<refsect1>
6171<title>LOCKING</title>
6172<para>
6173   Inherited from caller.
6174</para>
6175</refsect1>
6176<refsect1>
6177<title>RETURNS</title>
6178<para>
6179   0 on success, negative errno on failure
6180</para>
6181</refsect1>
6182</refentry>
6183
6184<refentry id="API-sata-set-spd-needed">
6185<refentryinfo>
6186 <title>LINUX</title>
6187 <productname>Kernel Hackers Manual</productname>
6188 <date>July 2017</date>
6189</refentryinfo>
6190<refmeta>
6191 <refentrytitle><phrase>sata_set_spd_needed</phrase></refentrytitle>
6192 <manvolnum>9</manvolnum>
6193 <refmiscinfo class="version">4.1.27</refmiscinfo>
6194</refmeta>
6195<refnamediv>
6196 <refname>sata_set_spd_needed</refname>
6197 <refpurpose>
6198     is SATA spd configuration needed
6199 </refpurpose>
6200</refnamediv>
6201<refsynopsisdiv>
6202 <title>Synopsis</title>
6203  <funcsynopsis><funcprototype>
6204   <funcdef>int <function>sata_set_spd_needed </function></funcdef>
6205   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
6206  </funcprototype></funcsynopsis>
6207</refsynopsisdiv>
6208<refsect1>
6209 <title>Arguments</title>
6210 <variablelist>
6211  <varlistentry>
6212   <term><parameter>link</parameter></term>
6213   <listitem>
6214    <para>
6215     Link in question
6216    </para>
6217   </listitem>
6218  </varlistentry>
6219 </variablelist>
6220</refsect1>
6221<refsect1>
6222<title>Description</title>
6223<para>
6224   Test whether the spd limit in SControl matches
6225   <parameter>link</parameter>-&gt;sata_spd_limit.  This function is used to determine
6226   whether hardreset is necessary to apply SATA spd
6227   configuration.
6228</para>
6229</refsect1>
6230<refsect1>
6231<title>LOCKING</title>
6232<para>
6233   Inherited from caller.
6234</para>
6235</refsect1>
6236<refsect1>
6237<title>RETURNS</title>
6238<para>
6239   1 if SATA spd configuration is needed, 0 otherwise.
6240</para>
6241</refsect1>
6242</refentry>
6243
6244<refentry id="API-ata-down-xfermask-limit">
6245<refentryinfo>
6246 <title>LINUX</title>
6247 <productname>Kernel Hackers Manual</productname>
6248 <date>July 2017</date>
6249</refentryinfo>
6250<refmeta>
6251 <refentrytitle><phrase>ata_down_xfermask_limit</phrase></refentrytitle>
6252 <manvolnum>9</manvolnum>
6253 <refmiscinfo class="version">4.1.27</refmiscinfo>
6254</refmeta>
6255<refnamediv>
6256 <refname>ata_down_xfermask_limit</refname>
6257 <refpurpose>
6258     adjust dev xfer masks downward
6259 </refpurpose>
6260</refnamediv>
6261<refsynopsisdiv>
6262 <title>Synopsis</title>
6263  <funcsynopsis><funcprototype>
6264   <funcdef>int <function>ata_down_xfermask_limit </function></funcdef>
6265   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6266   <paramdef>unsigned int <parameter>sel</parameter></paramdef>
6267  </funcprototype></funcsynopsis>
6268</refsynopsisdiv>
6269<refsect1>
6270 <title>Arguments</title>
6271 <variablelist>
6272  <varlistentry>
6273   <term><parameter>dev</parameter></term>
6274   <listitem>
6275    <para>
6276     Device to adjust xfer masks
6277    </para>
6278   </listitem>
6279  </varlistentry>
6280  <varlistentry>
6281   <term><parameter>sel</parameter></term>
6282   <listitem>
6283    <para>
6284     ATA_DNXFER_* selector
6285    </para>
6286   </listitem>
6287  </varlistentry>
6288 </variablelist>
6289</refsect1>
6290<refsect1>
6291<title>Description</title>
6292<para>
6293   Adjust xfer masks of <parameter>dev</parameter> downward.  Note that this function
6294   does not apply the change.  Invoking <function>ata_set_mode</function> afterwards
6295   will apply the limit.
6296</para>
6297</refsect1>
6298<refsect1>
6299<title>LOCKING</title>
6300<para>
6301   Inherited from caller.
6302</para>
6303</refsect1>
6304<refsect1>
6305<title>RETURNS</title>
6306<para>
6307   0 on success, negative errno on failure
6308</para>
6309</refsect1>
6310</refentry>
6311
6312<refentry id="API-ata-wait-ready">
6313<refentryinfo>
6314 <title>LINUX</title>
6315 <productname>Kernel Hackers Manual</productname>
6316 <date>July 2017</date>
6317</refentryinfo>
6318<refmeta>
6319 <refentrytitle><phrase>ata_wait_ready</phrase></refentrytitle>
6320 <manvolnum>9</manvolnum>
6321 <refmiscinfo class="version">4.1.27</refmiscinfo>
6322</refmeta>
6323<refnamediv>
6324 <refname>ata_wait_ready</refname>
6325 <refpurpose>
6326     wait for link to become ready
6327 </refpurpose>
6328</refnamediv>
6329<refsynopsisdiv>
6330 <title>Synopsis</title>
6331  <funcsynopsis><funcprototype>
6332   <funcdef>int <function>ata_wait_ready </function></funcdef>
6333   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
6334   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
6335   <paramdef>int (*<parameter>check_ready</parameter>)
6336     <funcparams>struct ata_link *link</funcparams></paramdef>
6337  </funcprototype></funcsynopsis>
6338</refsynopsisdiv>
6339<refsect1>
6340 <title>Arguments</title>
6341 <variablelist>
6342  <varlistentry>
6343   <term><parameter>link</parameter></term>
6344   <listitem>
6345    <para>
6346     link to be waited on
6347    </para>
6348   </listitem>
6349  </varlistentry>
6350  <varlistentry>
6351   <term><parameter>deadline</parameter></term>
6352   <listitem>
6353    <para>
6354     deadline jiffies for the operation
6355    </para>
6356   </listitem>
6357  </varlistentry>
6358  <varlistentry>
6359   <term><parameter>check_ready</parameter></term>
6360   <listitem>
6361    <para>
6362     callback to check link readiness
6363    </para>
6364   </listitem>
6365  </varlistentry>
6366 </variablelist>
6367</refsect1>
6368<refsect1>
6369<title>Description</title>
6370<para>
6371   Wait for <parameter>link</parameter> to become ready.  <parameter>check_ready</parameter> should return
6372   positive number if <parameter>link</parameter> is ready, 0 if it isn't, -ENODEV if
6373   link doesn't seem to be occupied, other errno for other error
6374   conditions.
6375   </para><para>
6376
6377   Transient -ENODEV conditions are allowed for
6378   ATA_TMOUT_FF_WAIT.
6379</para>
6380</refsect1>
6381<refsect1>
6382<title>LOCKING</title>
6383<para>
6384   EH context.
6385</para>
6386</refsect1>
6387<refsect1>
6388<title>RETURNS</title>
6389<para>
6390   0 if <parameter>linke</parameter> is ready before <parameter>deadline</parameter>; otherwise, -errno.
6391</para>
6392</refsect1>
6393</refentry>
6394
6395<refentry id="API-ata-dev-same-device">
6396<refentryinfo>
6397 <title>LINUX</title>
6398 <productname>Kernel Hackers Manual</productname>
6399 <date>July 2017</date>
6400</refentryinfo>
6401<refmeta>
6402 <refentrytitle><phrase>ata_dev_same_device</phrase></refentrytitle>
6403 <manvolnum>9</manvolnum>
6404 <refmiscinfo class="version">4.1.27</refmiscinfo>
6405</refmeta>
6406<refnamediv>
6407 <refname>ata_dev_same_device</refname>
6408 <refpurpose>
6409     Determine whether new ID matches configured device
6410 </refpurpose>
6411</refnamediv>
6412<refsynopsisdiv>
6413 <title>Synopsis</title>
6414  <funcsynopsis><funcprototype>
6415   <funcdef>int <function>ata_dev_same_device </function></funcdef>
6416   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6417   <paramdef>unsigned int <parameter>new_class</parameter></paramdef>
6418   <paramdef>const u16 * <parameter>new_id</parameter></paramdef>
6419  </funcprototype></funcsynopsis>
6420</refsynopsisdiv>
6421<refsect1>
6422 <title>Arguments</title>
6423 <variablelist>
6424  <varlistentry>
6425   <term><parameter>dev</parameter></term>
6426   <listitem>
6427    <para>
6428     device to compare against
6429    </para>
6430   </listitem>
6431  </varlistentry>
6432  <varlistentry>
6433   <term><parameter>new_class</parameter></term>
6434   <listitem>
6435    <para>
6436     class of the new device
6437    </para>
6438   </listitem>
6439  </varlistentry>
6440  <varlistentry>
6441   <term><parameter>new_id</parameter></term>
6442   <listitem>
6443    <para>
6444     IDENTIFY page of the new device
6445    </para>
6446   </listitem>
6447  </varlistentry>
6448 </variablelist>
6449</refsect1>
6450<refsect1>
6451<title>Description</title>
6452<para>
6453   Compare <parameter>new_class</parameter> and <parameter>new_id</parameter> against <parameter>dev</parameter> and determine
6454   whether <parameter>dev</parameter> is the device indicated by <parameter>new_class</parameter> and
6455   <parameter>new_id</parameter>.
6456</para>
6457</refsect1>
6458<refsect1>
6459<title>LOCKING</title>
6460<para>
6461   None.
6462</para>
6463</refsect1>
6464<refsect1>
6465<title>RETURNS</title>
6466<para>
6467   1 if <parameter>dev</parameter> matches <parameter>new_class</parameter> and <parameter>new_id</parameter>, 0 otherwise.
6468</para>
6469</refsect1>
6470</refentry>
6471
6472<refentry id="API-ata-dev-reread-id">
6473<refentryinfo>
6474 <title>LINUX</title>
6475 <productname>Kernel Hackers Manual</productname>
6476 <date>July 2017</date>
6477</refentryinfo>
6478<refmeta>
6479 <refentrytitle><phrase>ata_dev_reread_id</phrase></refentrytitle>
6480 <manvolnum>9</manvolnum>
6481 <refmiscinfo class="version">4.1.27</refmiscinfo>
6482</refmeta>
6483<refnamediv>
6484 <refname>ata_dev_reread_id</refname>
6485 <refpurpose>
6486     Re-read IDENTIFY data
6487 </refpurpose>
6488</refnamediv>
6489<refsynopsisdiv>
6490 <title>Synopsis</title>
6491  <funcsynopsis><funcprototype>
6492   <funcdef>int <function>ata_dev_reread_id </function></funcdef>
6493   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6494   <paramdef>unsigned int <parameter>readid_flags</parameter></paramdef>
6495  </funcprototype></funcsynopsis>
6496</refsynopsisdiv>
6497<refsect1>
6498 <title>Arguments</title>
6499 <variablelist>
6500  <varlistentry>
6501   <term><parameter>dev</parameter></term>
6502   <listitem>
6503    <para>
6504     target ATA device
6505    </para>
6506   </listitem>
6507  </varlistentry>
6508  <varlistentry>
6509   <term><parameter>readid_flags</parameter></term>
6510   <listitem>
6511    <para>
6512     read ID flags
6513    </para>
6514   </listitem>
6515  </varlistentry>
6516 </variablelist>
6517</refsect1>
6518<refsect1>
6519<title>Description</title>
6520<para>
6521   Re-read IDENTIFY page and make sure <parameter>dev</parameter> is still attached to
6522   the port.
6523</para>
6524</refsect1>
6525<refsect1>
6526<title>LOCKING</title>
6527<para>
6528   Kernel thread context (may sleep)
6529</para>
6530</refsect1>
6531<refsect1>
6532<title>RETURNS</title>
6533<para>
6534   0 on success, negative errno otherwise
6535</para>
6536</refsect1>
6537</refentry>
6538
6539<refentry id="API-ata-dev-revalidate">
6540<refentryinfo>
6541 <title>LINUX</title>
6542 <productname>Kernel Hackers Manual</productname>
6543 <date>July 2017</date>
6544</refentryinfo>
6545<refmeta>
6546 <refentrytitle><phrase>ata_dev_revalidate</phrase></refentrytitle>
6547 <manvolnum>9</manvolnum>
6548 <refmiscinfo class="version">4.1.27</refmiscinfo>
6549</refmeta>
6550<refnamediv>
6551 <refname>ata_dev_revalidate</refname>
6552 <refpurpose>
6553     Revalidate ATA device
6554 </refpurpose>
6555</refnamediv>
6556<refsynopsisdiv>
6557 <title>Synopsis</title>
6558  <funcsynopsis><funcprototype>
6559   <funcdef>int <function>ata_dev_revalidate </function></funcdef>
6560   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6561   <paramdef>unsigned int <parameter>new_class</parameter></paramdef>
6562   <paramdef>unsigned int <parameter>readid_flags</parameter></paramdef>
6563  </funcprototype></funcsynopsis>
6564</refsynopsisdiv>
6565<refsect1>
6566 <title>Arguments</title>
6567 <variablelist>
6568  <varlistentry>
6569   <term><parameter>dev</parameter></term>
6570   <listitem>
6571    <para>
6572     device to revalidate
6573    </para>
6574   </listitem>
6575  </varlistentry>
6576  <varlistentry>
6577   <term><parameter>new_class</parameter></term>
6578   <listitem>
6579    <para>
6580     new class code
6581    </para>
6582   </listitem>
6583  </varlistentry>
6584  <varlistentry>
6585   <term><parameter>readid_flags</parameter></term>
6586   <listitem>
6587    <para>
6588     read ID flags
6589    </para>
6590   </listitem>
6591  </varlistentry>
6592 </variablelist>
6593</refsect1>
6594<refsect1>
6595<title>Description</title>
6596<para>
6597   Re-read IDENTIFY page, make sure <parameter>dev</parameter> is still attached to the
6598   port and reconfigure it according to the new IDENTIFY page.
6599</para>
6600</refsect1>
6601<refsect1>
6602<title>LOCKING</title>
6603<para>
6604   Kernel thread context (may sleep)
6605</para>
6606</refsect1>
6607<refsect1>
6608<title>RETURNS</title>
6609<para>
6610   0 on success, negative errno otherwise
6611</para>
6612</refsect1>
6613</refentry>
6614
6615<refentry id="API-ata-is-40wire">
6616<refentryinfo>
6617 <title>LINUX</title>
6618 <productname>Kernel Hackers Manual</productname>
6619 <date>July 2017</date>
6620</refentryinfo>
6621<refmeta>
6622 <refentrytitle><phrase>ata_is_40wire</phrase></refentrytitle>
6623 <manvolnum>9</manvolnum>
6624 <refmiscinfo class="version">4.1.27</refmiscinfo>
6625</refmeta>
6626<refnamediv>
6627 <refname>ata_is_40wire</refname>
6628 <refpurpose>
6629     check drive side detection
6630 </refpurpose>
6631</refnamediv>
6632<refsynopsisdiv>
6633 <title>Synopsis</title>
6634  <funcsynopsis><funcprototype>
6635   <funcdef>int <function>ata_is_40wire </function></funcdef>
6636   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6637  </funcprototype></funcsynopsis>
6638</refsynopsisdiv>
6639<refsect1>
6640 <title>Arguments</title>
6641 <variablelist>
6642  <varlistentry>
6643   <term><parameter>dev</parameter></term>
6644   <listitem>
6645    <para>
6646     device
6647    </para>
6648   </listitem>
6649  </varlistentry>
6650 </variablelist>
6651</refsect1>
6652<refsect1>
6653<title>Description</title>
6654<para>
6655   Perform drive side detection decoding, allowing for device vendors
6656   who can't follow the documentation.
6657</para>
6658</refsect1>
6659</refentry>
6660
6661<refentry id="API-cable-is-40wire">
6662<refentryinfo>
6663 <title>LINUX</title>
6664 <productname>Kernel Hackers Manual</productname>
6665 <date>July 2017</date>
6666</refentryinfo>
6667<refmeta>
6668 <refentrytitle><phrase>cable_is_40wire</phrase></refentrytitle>
6669 <manvolnum>9</manvolnum>
6670 <refmiscinfo class="version">4.1.27</refmiscinfo>
6671</refmeta>
6672<refnamediv>
6673 <refname>cable_is_40wire</refname>
6674 <refpurpose>
6675     40/80/SATA decider
6676 </refpurpose>
6677</refnamediv>
6678<refsynopsisdiv>
6679 <title>Synopsis</title>
6680  <funcsynopsis><funcprototype>
6681   <funcdef>int <function>cable_is_40wire </function></funcdef>
6682   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
6683  </funcprototype></funcsynopsis>
6684</refsynopsisdiv>
6685<refsect1>
6686 <title>Arguments</title>
6687 <variablelist>
6688  <varlistentry>
6689   <term><parameter>ap</parameter></term>
6690   <listitem>
6691    <para>
6692     port to consider
6693    </para>
6694   </listitem>
6695  </varlistentry>
6696 </variablelist>
6697</refsect1>
6698<refsect1>
6699<title>Description</title>
6700<para>
6701   This function encapsulates the policy for speed management
6702   in one place. At the moment we don't cache the result but
6703   there is a good case for setting ap-&gt;cbl to the result when
6704   we are called with unknown cables (and figuring out if it
6705   impacts hotplug at all).
6706   </para><para>
6707
6708   Return 1 if the cable appears to be 40 wire.
6709</para>
6710</refsect1>
6711</refentry>
6712
6713<refentry id="API-ata-dev-xfermask">
6714<refentryinfo>
6715 <title>LINUX</title>
6716 <productname>Kernel Hackers Manual</productname>
6717 <date>July 2017</date>
6718</refentryinfo>
6719<refmeta>
6720 <refentrytitle><phrase>ata_dev_xfermask</phrase></refentrytitle>
6721 <manvolnum>9</manvolnum>
6722 <refmiscinfo class="version">4.1.27</refmiscinfo>
6723</refmeta>
6724<refnamediv>
6725 <refname>ata_dev_xfermask</refname>
6726 <refpurpose>
6727     Compute supported xfermask of the given device
6728 </refpurpose>
6729</refnamediv>
6730<refsynopsisdiv>
6731 <title>Synopsis</title>
6732  <funcsynopsis><funcprototype>
6733   <funcdef>void <function>ata_dev_xfermask </function></funcdef>
6734   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6735  </funcprototype></funcsynopsis>
6736</refsynopsisdiv>
6737<refsect1>
6738 <title>Arguments</title>
6739 <variablelist>
6740  <varlistentry>
6741   <term><parameter>dev</parameter></term>
6742   <listitem>
6743    <para>
6744     Device to compute xfermask for
6745    </para>
6746   </listitem>
6747  </varlistentry>
6748 </variablelist>
6749</refsect1>
6750<refsect1>
6751<title>Description</title>
6752<para>
6753   Compute supported xfermask of <parameter>dev</parameter> and store it in
6754   dev-&gt;*_mask.  This function is responsible for applying all
6755   known limits including host controller limits, device
6756   blacklist, etc...
6757</para>
6758</refsect1>
6759<refsect1>
6760<title>LOCKING</title>
6761<para>
6762   None.
6763</para>
6764</refsect1>
6765</refentry>
6766
6767<refentry id="API-ata-dev-set-xfermode">
6768<refentryinfo>
6769 <title>LINUX</title>
6770 <productname>Kernel Hackers Manual</productname>
6771 <date>July 2017</date>
6772</refentryinfo>
6773<refmeta>
6774 <refentrytitle><phrase>ata_dev_set_xfermode</phrase></refentrytitle>
6775 <manvolnum>9</manvolnum>
6776 <refmiscinfo class="version">4.1.27</refmiscinfo>
6777</refmeta>
6778<refnamediv>
6779 <refname>ata_dev_set_xfermode</refname>
6780 <refpurpose>
6781     Issue SET FEATURES - XFER MODE command
6782 </refpurpose>
6783</refnamediv>
6784<refsynopsisdiv>
6785 <title>Synopsis</title>
6786  <funcsynopsis><funcprototype>
6787   <funcdef>unsigned int <function>ata_dev_set_xfermode </function></funcdef>
6788   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6789  </funcprototype></funcsynopsis>
6790</refsynopsisdiv>
6791<refsect1>
6792 <title>Arguments</title>
6793 <variablelist>
6794  <varlistentry>
6795   <term><parameter>dev</parameter></term>
6796   <listitem>
6797    <para>
6798     Device to which command will be sent
6799    </para>
6800   </listitem>
6801  </varlistentry>
6802 </variablelist>
6803</refsect1>
6804<refsect1>
6805<title>Description</title>
6806<para>
6807   Issue SET FEATURES - XFER MODE command to device <parameter>dev</parameter>
6808   on port <parameter>ap</parameter>.
6809</para>
6810</refsect1>
6811<refsect1>
6812<title>LOCKING</title>
6813<para>
6814   PCI/etc. bus probe sem.
6815</para>
6816</refsect1>
6817<refsect1>
6818<title>RETURNS</title>
6819<para>
6820   0 on success, AC_ERR_* mask otherwise.
6821</para>
6822</refsect1>
6823</refentry>
6824
6825<refentry id="API-ata-dev-init-params">
6826<refentryinfo>
6827 <title>LINUX</title>
6828 <productname>Kernel Hackers Manual</productname>
6829 <date>July 2017</date>
6830</refentryinfo>
6831<refmeta>
6832 <refentrytitle><phrase>ata_dev_init_params</phrase></refentrytitle>
6833 <manvolnum>9</manvolnum>
6834 <refmiscinfo class="version">4.1.27</refmiscinfo>
6835</refmeta>
6836<refnamediv>
6837 <refname>ata_dev_init_params</refname>
6838 <refpurpose>
6839     Issue INIT DEV PARAMS command
6840 </refpurpose>
6841</refnamediv>
6842<refsynopsisdiv>
6843 <title>Synopsis</title>
6844  <funcsynopsis><funcprototype>
6845   <funcdef>unsigned int <function>ata_dev_init_params </function></funcdef>
6846   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
6847   <paramdef>u16 <parameter>heads</parameter></paramdef>
6848   <paramdef>u16 <parameter>sectors</parameter></paramdef>
6849  </funcprototype></funcsynopsis>
6850</refsynopsisdiv>
6851<refsect1>
6852 <title>Arguments</title>
6853 <variablelist>
6854  <varlistentry>
6855   <term><parameter>dev</parameter></term>
6856   <listitem>
6857    <para>
6858     Device to which command will be sent
6859    </para>
6860   </listitem>
6861  </varlistentry>
6862  <varlistentry>
6863   <term><parameter>heads</parameter></term>
6864   <listitem>
6865    <para>
6866     Number of heads (taskfile parameter)
6867    </para>
6868   </listitem>
6869  </varlistentry>
6870  <varlistentry>
6871   <term><parameter>sectors</parameter></term>
6872   <listitem>
6873    <para>
6874     Number of sectors (taskfile parameter)
6875    </para>
6876   </listitem>
6877  </varlistentry>
6878 </variablelist>
6879</refsect1>
6880<refsect1>
6881<title>LOCKING</title>
6882<para>
6883   Kernel thread context (may sleep)
6884</para>
6885</refsect1>
6886<refsect1>
6887<title>RETURNS</title>
6888<para>
6889   0 on success, AC_ERR_* mask otherwise.
6890</para>
6891</refsect1>
6892</refentry>
6893
6894<refentry id="API-ata-sg-clean">
6895<refentryinfo>
6896 <title>LINUX</title>
6897 <productname>Kernel Hackers Manual</productname>
6898 <date>July 2017</date>
6899</refentryinfo>
6900<refmeta>
6901 <refentrytitle><phrase>ata_sg_clean</phrase></refentrytitle>
6902 <manvolnum>9</manvolnum>
6903 <refmiscinfo class="version">4.1.27</refmiscinfo>
6904</refmeta>
6905<refnamediv>
6906 <refname>ata_sg_clean</refname>
6907 <refpurpose>
6908     Unmap DMA memory associated with command
6909 </refpurpose>
6910</refnamediv>
6911<refsynopsisdiv>
6912 <title>Synopsis</title>
6913  <funcsynopsis><funcprototype>
6914   <funcdef>void <function>ata_sg_clean </function></funcdef>
6915   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
6916  </funcprototype></funcsynopsis>
6917</refsynopsisdiv>
6918<refsect1>
6919 <title>Arguments</title>
6920 <variablelist>
6921  <varlistentry>
6922   <term><parameter>qc</parameter></term>
6923   <listitem>
6924    <para>
6925     Command containing DMA memory to be released
6926    </para>
6927   </listitem>
6928  </varlistentry>
6929 </variablelist>
6930</refsect1>
6931<refsect1>
6932<title>Description</title>
6933<para>
6934   Unmap all mapped DMA memory associated with this command.
6935</para>
6936</refsect1>
6937<refsect1>
6938<title>LOCKING</title>
6939<para>
6940   spin_lock_irqsave(host lock)
6941</para>
6942</refsect1>
6943</refentry>
6944
6945<refentry id="API-atapi-check-dma">
6946<refentryinfo>
6947 <title>LINUX</title>
6948 <productname>Kernel Hackers Manual</productname>
6949 <date>July 2017</date>
6950</refentryinfo>
6951<refmeta>
6952 <refentrytitle><phrase>atapi_check_dma</phrase></refentrytitle>
6953 <manvolnum>9</manvolnum>
6954 <refmiscinfo class="version">4.1.27</refmiscinfo>
6955</refmeta>
6956<refnamediv>
6957 <refname>atapi_check_dma</refname>
6958 <refpurpose>
6959     Check whether ATAPI DMA can be supported
6960 </refpurpose>
6961</refnamediv>
6962<refsynopsisdiv>
6963 <title>Synopsis</title>
6964  <funcsynopsis><funcprototype>
6965   <funcdef>int <function>atapi_check_dma </function></funcdef>
6966   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
6967  </funcprototype></funcsynopsis>
6968</refsynopsisdiv>
6969<refsect1>
6970 <title>Arguments</title>
6971 <variablelist>
6972  <varlistentry>
6973   <term><parameter>qc</parameter></term>
6974   <listitem>
6975    <para>
6976     Metadata associated with taskfile to check
6977    </para>
6978   </listitem>
6979  </varlistentry>
6980 </variablelist>
6981</refsect1>
6982<refsect1>
6983<title>Description</title>
6984<para>
6985   Allow low-level driver to filter ATA PACKET commands, returning
6986   a status indicating whether or not it is OK to use DMA for the
6987   supplied PACKET command.
6988</para>
6989</refsect1>
6990<refsect1>
6991<title>LOCKING</title>
6992<para>
6993   spin_lock_irqsave(host lock)
6994</para>
6995</refsect1>
6996<refsect1>
6997<title>RETURNS</title>
6998<para>
6999   0 when ATAPI DMA can be used
7000   nonzero otherwise
7001</para>
7002</refsect1>
7003</refentry>
7004
7005<refentry id="API-ata-sg-setup">
7006<refentryinfo>
7007 <title>LINUX</title>
7008 <productname>Kernel Hackers Manual</productname>
7009 <date>July 2017</date>
7010</refentryinfo>
7011<refmeta>
7012 <refentrytitle><phrase>ata_sg_setup</phrase></refentrytitle>
7013 <manvolnum>9</manvolnum>
7014 <refmiscinfo class="version">4.1.27</refmiscinfo>
7015</refmeta>
7016<refnamediv>
7017 <refname>ata_sg_setup</refname>
7018 <refpurpose>
7019     DMA-map the scatter-gather table associated with a command.
7020 </refpurpose>
7021</refnamediv>
7022<refsynopsisdiv>
7023 <title>Synopsis</title>
7024  <funcsynopsis><funcprototype>
7025   <funcdef>int <function>ata_sg_setup </function></funcdef>
7026   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
7027  </funcprototype></funcsynopsis>
7028</refsynopsisdiv>
7029<refsect1>
7030 <title>Arguments</title>
7031 <variablelist>
7032  <varlistentry>
7033   <term><parameter>qc</parameter></term>
7034   <listitem>
7035    <para>
7036     Command with scatter-gather table to be mapped.
7037    </para>
7038   </listitem>
7039  </varlistentry>
7040 </variablelist>
7041</refsect1>
7042<refsect1>
7043<title>Description</title>
7044<para>
7045   DMA-map the scatter-gather table associated with queued_cmd <parameter>qc</parameter>.
7046</para>
7047</refsect1>
7048<refsect1>
7049<title>LOCKING</title>
7050<para>
7051   spin_lock_irqsave(host lock)
7052</para>
7053</refsect1>
7054<refsect1>
7055<title>RETURNS</title>
7056<para>
7057   Zero on success, negative on error.
7058</para>
7059</refsect1>
7060</refentry>
7061
7062<refentry id="API-swap-buf-le16">
7063<refentryinfo>
7064 <title>LINUX</title>
7065 <productname>Kernel Hackers Manual</productname>
7066 <date>July 2017</date>
7067</refentryinfo>
7068<refmeta>
7069 <refentrytitle><phrase>swap_buf_le16</phrase></refentrytitle>
7070 <manvolnum>9</manvolnum>
7071 <refmiscinfo class="version">4.1.27</refmiscinfo>
7072</refmeta>
7073<refnamediv>
7074 <refname>swap_buf_le16</refname>
7075 <refpurpose>
7076     swap halves of 16-bit words in place
7077 </refpurpose>
7078</refnamediv>
7079<refsynopsisdiv>
7080 <title>Synopsis</title>
7081  <funcsynopsis><funcprototype>
7082   <funcdef>void <function>swap_buf_le16 </function></funcdef>
7083   <paramdef>u16 * <parameter>buf</parameter></paramdef>
7084   <paramdef>unsigned int <parameter>buf_words</parameter></paramdef>
7085  </funcprototype></funcsynopsis>
7086</refsynopsisdiv>
7087<refsect1>
7088 <title>Arguments</title>
7089 <variablelist>
7090  <varlistentry>
7091   <term><parameter>buf</parameter></term>
7092   <listitem>
7093    <para>
7094     Buffer to swap
7095    </para>
7096   </listitem>
7097  </varlistentry>
7098  <varlistentry>
7099   <term><parameter>buf_words</parameter></term>
7100   <listitem>
7101    <para>
7102     Number of 16-bit words in buffer.
7103    </para>
7104   </listitem>
7105  </varlistentry>
7106 </variablelist>
7107</refsect1>
7108<refsect1>
7109<title>Description</title>
7110<para>
7111   Swap halves of 16-bit words if needed to convert from
7112   little-endian byte order to native cpu byte order, or
7113   vice-versa.
7114</para>
7115</refsect1>
7116<refsect1>
7117<title>LOCKING</title>
7118<para>
7119   Inherited from caller.
7120</para>
7121</refsect1>
7122</refentry>
7123
7124<refentry id="API-ata-qc-new-init">
7125<refentryinfo>
7126 <title>LINUX</title>
7127 <productname>Kernel Hackers Manual</productname>
7128 <date>July 2017</date>
7129</refentryinfo>
7130<refmeta>
7131 <refentrytitle><phrase>ata_qc_new_init</phrase></refentrytitle>
7132 <manvolnum>9</manvolnum>
7133 <refmiscinfo class="version">4.1.27</refmiscinfo>
7134</refmeta>
7135<refnamediv>
7136 <refname>ata_qc_new_init</refname>
7137 <refpurpose>
7138     Request an available ATA command, and initialize it
7139 </refpurpose>
7140</refnamediv>
7141<refsynopsisdiv>
7142 <title>Synopsis</title>
7143  <funcsynopsis><funcprototype>
7144   <funcdef>struct ata_queued_cmd * <function>ata_qc_new_init </function></funcdef>
7145   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
7146   <paramdef>int <parameter>tag</parameter></paramdef>
7147  </funcprototype></funcsynopsis>
7148</refsynopsisdiv>
7149<refsect1>
7150 <title>Arguments</title>
7151 <variablelist>
7152  <varlistentry>
7153   <term><parameter>dev</parameter></term>
7154   <listitem>
7155    <para>
7156     Device from whom we request an available command structure
7157    </para>
7158   </listitem>
7159  </varlistentry>
7160  <varlistentry>
7161   <term><parameter>tag</parameter></term>
7162   <listitem>
7163    <para>
7164     -- undescribed --
7165    </para>
7166   </listitem>
7167  </varlistentry>
7168 </variablelist>
7169</refsect1>
7170<refsect1>
7171<title>LOCKING</title>
7172<para>
7173   None.
7174</para>
7175</refsect1>
7176</refentry>
7177
7178<refentry id="API-ata-qc-free">
7179<refentryinfo>
7180 <title>LINUX</title>
7181 <productname>Kernel Hackers Manual</productname>
7182 <date>July 2017</date>
7183</refentryinfo>
7184<refmeta>
7185 <refentrytitle><phrase>ata_qc_free</phrase></refentrytitle>
7186 <manvolnum>9</manvolnum>
7187 <refmiscinfo class="version">4.1.27</refmiscinfo>
7188</refmeta>
7189<refnamediv>
7190 <refname>ata_qc_free</refname>
7191 <refpurpose>
7192     free unused ata_queued_cmd
7193 </refpurpose>
7194</refnamediv>
7195<refsynopsisdiv>
7196 <title>Synopsis</title>
7197  <funcsynopsis><funcprototype>
7198   <funcdef>void <function>ata_qc_free </function></funcdef>
7199   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
7200  </funcprototype></funcsynopsis>
7201</refsynopsisdiv>
7202<refsect1>
7203 <title>Arguments</title>
7204 <variablelist>
7205  <varlistentry>
7206   <term><parameter>qc</parameter></term>
7207   <listitem>
7208    <para>
7209     Command to complete
7210    </para>
7211   </listitem>
7212  </varlistentry>
7213 </variablelist>
7214</refsect1>
7215<refsect1>
7216<title>Description</title>
7217<para>
7218   Designed to free unused ata_queued_cmd object
7219   in case something prevents using it.
7220</para>
7221</refsect1>
7222<refsect1>
7223<title>LOCKING</title>
7224<para>
7225   spin_lock_irqsave(host lock)
7226</para>
7227</refsect1>
7228</refentry>
7229
7230<refentry id="API-ata-qc-issue">
7231<refentryinfo>
7232 <title>LINUX</title>
7233 <productname>Kernel Hackers Manual</productname>
7234 <date>July 2017</date>
7235</refentryinfo>
7236<refmeta>
7237 <refentrytitle><phrase>ata_qc_issue</phrase></refentrytitle>
7238 <manvolnum>9</manvolnum>
7239 <refmiscinfo class="version">4.1.27</refmiscinfo>
7240</refmeta>
7241<refnamediv>
7242 <refname>ata_qc_issue</refname>
7243 <refpurpose>
7244     issue taskfile to device
7245 </refpurpose>
7246</refnamediv>
7247<refsynopsisdiv>
7248 <title>Synopsis</title>
7249  <funcsynopsis><funcprototype>
7250   <funcdef>void <function>ata_qc_issue </function></funcdef>
7251   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
7252  </funcprototype></funcsynopsis>
7253</refsynopsisdiv>
7254<refsect1>
7255 <title>Arguments</title>
7256 <variablelist>
7257  <varlistentry>
7258   <term><parameter>qc</parameter></term>
7259   <listitem>
7260    <para>
7261     command to issue to device
7262    </para>
7263   </listitem>
7264  </varlistentry>
7265 </variablelist>
7266</refsect1>
7267<refsect1>
7268<title>Description</title>
7269<para>
7270   Prepare an ATA command to submission to device.
7271   This includes mapping the data into a DMA-able
7272   area, filling in the S/G table, and finally
7273   writing the taskfile to hardware, starting the command.
7274</para>
7275</refsect1>
7276<refsect1>
7277<title>LOCKING</title>
7278<para>
7279   spin_lock_irqsave(host lock)
7280</para>
7281</refsect1>
7282</refentry>
7283
7284<refentry id="API-ata-phys-link-online">
7285<refentryinfo>
7286 <title>LINUX</title>
7287 <productname>Kernel Hackers Manual</productname>
7288 <date>July 2017</date>
7289</refentryinfo>
7290<refmeta>
7291 <refentrytitle><phrase>ata_phys_link_online</phrase></refentrytitle>
7292 <manvolnum>9</manvolnum>
7293 <refmiscinfo class="version">4.1.27</refmiscinfo>
7294</refmeta>
7295<refnamediv>
7296 <refname>ata_phys_link_online</refname>
7297 <refpurpose>
7298     test whether the given link is online
7299 </refpurpose>
7300</refnamediv>
7301<refsynopsisdiv>
7302 <title>Synopsis</title>
7303  <funcsynopsis><funcprototype>
7304   <funcdef>bool <function>ata_phys_link_online </function></funcdef>
7305   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
7306  </funcprototype></funcsynopsis>
7307</refsynopsisdiv>
7308<refsect1>
7309 <title>Arguments</title>
7310 <variablelist>
7311  <varlistentry>
7312   <term><parameter>link</parameter></term>
7313   <listitem>
7314    <para>
7315     ATA link to test
7316    </para>
7317   </listitem>
7318  </varlistentry>
7319 </variablelist>
7320</refsect1>
7321<refsect1>
7322<title>Description</title>
7323<para>
7324   Test whether <parameter>link</parameter> is online.  Note that this function returns
7325   0 if online status of <parameter>link</parameter> cannot be obtained, so
7326   ata_link_online(link) != !ata_link_offline(link).
7327</para>
7328</refsect1>
7329<refsect1>
7330<title>LOCKING</title>
7331<para>
7332   None.
7333</para>
7334</refsect1>
7335<refsect1>
7336<title>RETURNS</title>
7337<para>
7338   True if the port online status is available and online.
7339</para>
7340</refsect1>
7341</refentry>
7342
7343<refentry id="API-ata-phys-link-offline">
7344<refentryinfo>
7345 <title>LINUX</title>
7346 <productname>Kernel Hackers Manual</productname>
7347 <date>July 2017</date>
7348</refentryinfo>
7349<refmeta>
7350 <refentrytitle><phrase>ata_phys_link_offline</phrase></refentrytitle>
7351 <manvolnum>9</manvolnum>
7352 <refmiscinfo class="version">4.1.27</refmiscinfo>
7353</refmeta>
7354<refnamediv>
7355 <refname>ata_phys_link_offline</refname>
7356 <refpurpose>
7357     test whether the given link is offline
7358 </refpurpose>
7359</refnamediv>
7360<refsynopsisdiv>
7361 <title>Synopsis</title>
7362  <funcsynopsis><funcprototype>
7363   <funcdef>bool <function>ata_phys_link_offline </function></funcdef>
7364   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
7365  </funcprototype></funcsynopsis>
7366</refsynopsisdiv>
7367<refsect1>
7368 <title>Arguments</title>
7369 <variablelist>
7370  <varlistentry>
7371   <term><parameter>link</parameter></term>
7372   <listitem>
7373    <para>
7374     ATA link to test
7375    </para>
7376   </listitem>
7377  </varlistentry>
7378 </variablelist>
7379</refsect1>
7380<refsect1>
7381<title>Description</title>
7382<para>
7383   Test whether <parameter>link</parameter> is offline.  Note that this function
7384   returns 0 if offline status of <parameter>link</parameter> cannot be obtained, so
7385   ata_link_online(link) != !ata_link_offline(link).
7386</para>
7387</refsect1>
7388<refsect1>
7389<title>LOCKING</title>
7390<para>
7391   None.
7392</para>
7393</refsect1>
7394<refsect1>
7395<title>RETURNS</title>
7396<para>
7397   True if the port offline status is available and offline.
7398</para>
7399</refsect1>
7400</refentry>
7401
7402<refentry id="API-ata-dev-init">
7403<refentryinfo>
7404 <title>LINUX</title>
7405 <productname>Kernel Hackers Manual</productname>
7406 <date>July 2017</date>
7407</refentryinfo>
7408<refmeta>
7409 <refentrytitle><phrase>ata_dev_init</phrase></refentrytitle>
7410 <manvolnum>9</manvolnum>
7411 <refmiscinfo class="version">4.1.27</refmiscinfo>
7412</refmeta>
7413<refnamediv>
7414 <refname>ata_dev_init</refname>
7415 <refpurpose>
7416     Initialize an ata_device structure
7417 </refpurpose>
7418</refnamediv>
7419<refsynopsisdiv>
7420 <title>Synopsis</title>
7421  <funcsynopsis><funcprototype>
7422   <funcdef>void <function>ata_dev_init </function></funcdef>
7423   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
7424  </funcprototype></funcsynopsis>
7425</refsynopsisdiv>
7426<refsect1>
7427 <title>Arguments</title>
7428 <variablelist>
7429  <varlistentry>
7430   <term><parameter>dev</parameter></term>
7431   <listitem>
7432    <para>
7433     Device structure to initialize
7434    </para>
7435   </listitem>
7436  </varlistentry>
7437 </variablelist>
7438</refsect1>
7439<refsect1>
7440<title>Description</title>
7441<para>
7442   Initialize <parameter>dev</parameter> in preparation for probing.
7443</para>
7444</refsect1>
7445<refsect1>
7446<title>LOCKING</title>
7447<para>
7448   Inherited from caller.
7449</para>
7450</refsect1>
7451</refentry>
7452
7453<refentry id="API-ata-link-init">
7454<refentryinfo>
7455 <title>LINUX</title>
7456 <productname>Kernel Hackers Manual</productname>
7457 <date>July 2017</date>
7458</refentryinfo>
7459<refmeta>
7460 <refentrytitle><phrase>ata_link_init</phrase></refentrytitle>
7461 <manvolnum>9</manvolnum>
7462 <refmiscinfo class="version">4.1.27</refmiscinfo>
7463</refmeta>
7464<refnamediv>
7465 <refname>ata_link_init</refname>
7466 <refpurpose>
7467     Initialize an ata_link structure
7468 </refpurpose>
7469</refnamediv>
7470<refsynopsisdiv>
7471 <title>Synopsis</title>
7472  <funcsynopsis><funcprototype>
7473   <funcdef>void <function>ata_link_init </function></funcdef>
7474   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
7475   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
7476   <paramdef>int <parameter>pmp</parameter></paramdef>
7477  </funcprototype></funcsynopsis>
7478</refsynopsisdiv>
7479<refsect1>
7480 <title>Arguments</title>
7481 <variablelist>
7482  <varlistentry>
7483   <term><parameter>ap</parameter></term>
7484   <listitem>
7485    <para>
7486     ATA port link is attached to
7487    </para>
7488   </listitem>
7489  </varlistentry>
7490  <varlistentry>
7491   <term><parameter>link</parameter></term>
7492   <listitem>
7493    <para>
7494     Link structure to initialize
7495    </para>
7496   </listitem>
7497  </varlistentry>
7498  <varlistentry>
7499   <term><parameter>pmp</parameter></term>
7500   <listitem>
7501    <para>
7502     Port multiplier port number
7503    </para>
7504   </listitem>
7505  </varlistentry>
7506 </variablelist>
7507</refsect1>
7508<refsect1>
7509<title>Description</title>
7510<para>
7511   Initialize <parameter>link</parameter>.
7512</para>
7513</refsect1>
7514<refsect1>
7515<title>LOCKING</title>
7516<para>
7517   Kernel thread context (may sleep)
7518</para>
7519</refsect1>
7520</refentry>
7521
7522<refentry id="API-sata-link-init-spd">
7523<refentryinfo>
7524 <title>LINUX</title>
7525 <productname>Kernel Hackers Manual</productname>
7526 <date>July 2017</date>
7527</refentryinfo>
7528<refmeta>
7529 <refentrytitle><phrase>sata_link_init_spd</phrase></refentrytitle>
7530 <manvolnum>9</manvolnum>
7531 <refmiscinfo class="version">4.1.27</refmiscinfo>
7532</refmeta>
7533<refnamediv>
7534 <refname>sata_link_init_spd</refname>
7535 <refpurpose>
7536     Initialize link-&gt;sata_spd_limit
7537 </refpurpose>
7538</refnamediv>
7539<refsynopsisdiv>
7540 <title>Synopsis</title>
7541  <funcsynopsis><funcprototype>
7542   <funcdef>int <function>sata_link_init_spd </function></funcdef>
7543   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
7544  </funcprototype></funcsynopsis>
7545</refsynopsisdiv>
7546<refsect1>
7547 <title>Arguments</title>
7548 <variablelist>
7549  <varlistentry>
7550   <term><parameter>link</parameter></term>
7551   <listitem>
7552    <para>
7553     Link to configure sata_spd_limit for
7554    </para>
7555   </listitem>
7556  </varlistentry>
7557 </variablelist>
7558</refsect1>
7559<refsect1>
7560<title>Description</title>
7561<para>
7562   Initialize <parameter>link</parameter>-&gt;[hw_]sata_spd_limit to the currently
7563   configured value.
7564</para>
7565</refsect1>
7566<refsect1>
7567<title>LOCKING</title>
7568<para>
7569   Kernel thread context (may sleep).
7570</para>
7571</refsect1>
7572<refsect1>
7573<title>RETURNS</title>
7574<para>
7575   0 on success, -errno on failure.
7576</para>
7577</refsect1>
7578</refentry>
7579
7580<refentry id="API-ata-port-alloc">
7581<refentryinfo>
7582 <title>LINUX</title>
7583 <productname>Kernel Hackers Manual</productname>
7584 <date>July 2017</date>
7585</refentryinfo>
7586<refmeta>
7587 <refentrytitle><phrase>ata_port_alloc</phrase></refentrytitle>
7588 <manvolnum>9</manvolnum>
7589 <refmiscinfo class="version">4.1.27</refmiscinfo>
7590</refmeta>
7591<refnamediv>
7592 <refname>ata_port_alloc</refname>
7593 <refpurpose>
7594     allocate and initialize basic ATA port resources
7595 </refpurpose>
7596</refnamediv>
7597<refsynopsisdiv>
7598 <title>Synopsis</title>
7599  <funcsynopsis><funcprototype>
7600   <funcdef>struct ata_port * <function>ata_port_alloc </function></funcdef>
7601   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
7602  </funcprototype></funcsynopsis>
7603</refsynopsisdiv>
7604<refsect1>
7605 <title>Arguments</title>
7606 <variablelist>
7607  <varlistentry>
7608   <term><parameter>host</parameter></term>
7609   <listitem>
7610    <para>
7611     ATA host this allocated port belongs to
7612    </para>
7613   </listitem>
7614  </varlistentry>
7615 </variablelist>
7616</refsect1>
7617<refsect1>
7618<title>Description</title>
7619<para>
7620   Allocate and initialize basic ATA port resources.
7621</para>
7622</refsect1>
7623<refsect1>
7624<title>RETURNS</title>
7625<para>
7626   Allocate ATA port on success, NULL on failure.
7627</para>
7628</refsect1>
7629<refsect1>
7630<title>LOCKING</title>
7631<para>
7632   Inherited from calling layer (may sleep).
7633</para>
7634</refsect1>
7635</refentry>
7636
7637<refentry id="API-ata-finalize-port-ops">
7638<refentryinfo>
7639 <title>LINUX</title>
7640 <productname>Kernel Hackers Manual</productname>
7641 <date>July 2017</date>
7642</refentryinfo>
7643<refmeta>
7644 <refentrytitle><phrase>ata_finalize_port_ops</phrase></refentrytitle>
7645 <manvolnum>9</manvolnum>
7646 <refmiscinfo class="version">4.1.27</refmiscinfo>
7647</refmeta>
7648<refnamediv>
7649 <refname>ata_finalize_port_ops</refname>
7650 <refpurpose>
7651     finalize ata_port_operations
7652 </refpurpose>
7653</refnamediv>
7654<refsynopsisdiv>
7655 <title>Synopsis</title>
7656  <funcsynopsis><funcprototype>
7657   <funcdef>void <function>ata_finalize_port_ops </function></funcdef>
7658   <paramdef>struct ata_port_operations * <parameter>ops</parameter></paramdef>
7659  </funcprototype></funcsynopsis>
7660</refsynopsisdiv>
7661<refsect1>
7662 <title>Arguments</title>
7663 <variablelist>
7664  <varlistentry>
7665   <term><parameter>ops</parameter></term>
7666   <listitem>
7667    <para>
7668     ata_port_operations to finalize
7669    </para>
7670   </listitem>
7671  </varlistentry>
7672 </variablelist>
7673</refsect1>
7674<refsect1>
7675<title>Description</title>
7676<para>
7677   An ata_port_operations can inherit from another ops and that
7678   ops can again inherit from another.  This can go on as many
7679   times as necessary as long as there is no loop in the
7680   inheritance chain.
7681   </para><para>
7682
7683   Ops tables are finalized when the host is started.  NULL or
7684   unspecified entries are inherited from the closet ancestor
7685   which has the method and the entry is populated with it.
7686   After finalization, the ops table directly points to all the
7687   methods and -&gt;inherits is no longer necessary and cleared.
7688   </para><para>
7689
7690   Using ATA_OP_NULL, inheriting ops can force a method to NULL.
7691</para>
7692</refsect1>
7693<refsect1>
7694<title>LOCKING</title>
7695<para>
7696   None.
7697</para>
7698</refsect1>
7699</refentry>
7700
7701<refentry id="API-ata-port-detach">
7702<refentryinfo>
7703 <title>LINUX</title>
7704 <productname>Kernel Hackers Manual</productname>
7705 <date>July 2017</date>
7706</refentryinfo>
7707<refmeta>
7708 <refentrytitle><phrase>ata_port_detach</phrase></refentrytitle>
7709 <manvolnum>9</manvolnum>
7710 <refmiscinfo class="version">4.1.27</refmiscinfo>
7711</refmeta>
7712<refnamediv>
7713 <refname>ata_port_detach</refname>
7714 <refpurpose>
7715     Detach ATA port in prepration of device removal
7716 </refpurpose>
7717</refnamediv>
7718<refsynopsisdiv>
7719 <title>Synopsis</title>
7720  <funcsynopsis><funcprototype>
7721   <funcdef>void <function>ata_port_detach </function></funcdef>
7722   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
7723  </funcprototype></funcsynopsis>
7724</refsynopsisdiv>
7725<refsect1>
7726 <title>Arguments</title>
7727 <variablelist>
7728  <varlistentry>
7729   <term><parameter>ap</parameter></term>
7730   <listitem>
7731    <para>
7732     ATA port to be detached
7733    </para>
7734   </listitem>
7735  </varlistentry>
7736 </variablelist>
7737</refsect1>
7738<refsect1>
7739<title>Description</title>
7740<para>
7741   Detach all ATA devices and the associated SCSI devices of <parameter>ap</parameter>;
7742   then, remove the associated SCSI host.  <parameter>ap</parameter> is guaranteed to
7743   be quiescent on return from this function.
7744</para>
7745</refsect1>
7746<refsect1>
7747<title>LOCKING</title>
7748<para>
7749   Kernel thread context (may sleep).
7750</para>
7751</refsect1>
7752</refentry>
7753
7754  </chapter>
7755
7756  <chapter id="libataScsiInt">
7757     <title>libata SCSI translation/emulation</title>
7758<!-- drivers/ata/libata-scsi.c -->
7759<refentry id="API-ata-std-bios-param">
7760<refentryinfo>
7761 <title>LINUX</title>
7762 <productname>Kernel Hackers Manual</productname>
7763 <date>July 2017</date>
7764</refentryinfo>
7765<refmeta>
7766 <refentrytitle><phrase>ata_std_bios_param</phrase></refentrytitle>
7767 <manvolnum>9</manvolnum>
7768 <refmiscinfo class="version">4.1.27</refmiscinfo>
7769</refmeta>
7770<refnamediv>
7771 <refname>ata_std_bios_param</refname>
7772 <refpurpose>
7773  generic bios head/sector/cylinder calculator used by sd.
7774 </refpurpose>
7775</refnamediv>
7776<refsynopsisdiv>
7777 <title>Synopsis</title>
7778  <funcsynopsis><funcprototype>
7779   <funcdef>int <function>ata_std_bios_param </function></funcdef>
7780   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
7781   <paramdef>struct block_device * <parameter>bdev</parameter></paramdef>
7782   <paramdef>sector_t <parameter>capacity</parameter></paramdef>
7783   <paramdef>int <parameter>geom[]</parameter></paramdef>
7784  </funcprototype></funcsynopsis>
7785</refsynopsisdiv>
7786<refsect1>
7787 <title>Arguments</title>
7788 <variablelist>
7789  <varlistentry>
7790   <term><parameter>sdev</parameter></term>
7791   <listitem>
7792    <para>
7793     SCSI device for which BIOS geometry is to be determined
7794    </para>
7795   </listitem>
7796  </varlistentry>
7797  <varlistentry>
7798   <term><parameter>bdev</parameter></term>
7799   <listitem>
7800    <para>
7801     block device associated with <parameter>sdev</parameter>
7802    </para>
7803   </listitem>
7804  </varlistentry>
7805  <varlistentry>
7806   <term><parameter>capacity</parameter></term>
7807   <listitem>
7808    <para>
7809     capacity of SCSI device
7810    </para>
7811   </listitem>
7812  </varlistentry>
7813  <varlistentry>
7814   <term><parameter>geom[]</parameter></term>
7815   <listitem>
7816    <para>
7817     location to which geometry will be output
7818    </para>
7819   </listitem>
7820  </varlistentry>
7821 </variablelist>
7822</refsect1>
7823<refsect1>
7824<title>Description</title>
7825<para>
7826   Generic bios head/sector/cylinder calculator
7827   used by sd. Most BIOSes nowadays expect a XXX/255/16  (CHS)
7828   mapping. Some situations may arise where the disk is not
7829   bootable if this is not used.
7830</para>
7831</refsect1>
7832<refsect1>
7833<title>LOCKING</title>
7834<para>
7835   Defined by the SCSI layer.  We don't really care.
7836</para>
7837</refsect1>
7838<refsect1>
7839<title>RETURNS</title>
7840<para>
7841   Zero.
7842</para>
7843</refsect1>
7844</refentry>
7845
7846<refentry id="API-ata-scsi-unlock-native-capacity">
7847<refentryinfo>
7848 <title>LINUX</title>
7849 <productname>Kernel Hackers Manual</productname>
7850 <date>July 2017</date>
7851</refentryinfo>
7852<refmeta>
7853 <refentrytitle><phrase>ata_scsi_unlock_native_capacity</phrase></refentrytitle>
7854 <manvolnum>9</manvolnum>
7855 <refmiscinfo class="version">4.1.27</refmiscinfo>
7856</refmeta>
7857<refnamediv>
7858 <refname>ata_scsi_unlock_native_capacity</refname>
7859 <refpurpose>
7860     unlock native capacity
7861 </refpurpose>
7862</refnamediv>
7863<refsynopsisdiv>
7864 <title>Synopsis</title>
7865  <funcsynopsis><funcprototype>
7866   <funcdef>void <function>ata_scsi_unlock_native_capacity </function></funcdef>
7867   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
7868  </funcprototype></funcsynopsis>
7869</refsynopsisdiv>
7870<refsect1>
7871 <title>Arguments</title>
7872 <variablelist>
7873  <varlistentry>
7874   <term><parameter>sdev</parameter></term>
7875   <listitem>
7876    <para>
7877     SCSI device to adjust device capacity for
7878    </para>
7879   </listitem>
7880  </varlistentry>
7881 </variablelist>
7882</refsect1>
7883<refsect1>
7884<title>Description</title>
7885<para>
7886   This function is called if a partition on <parameter>sdev</parameter> extends beyond
7887   the end of the device.  It requests EH to unlock HPA.
7888</para>
7889</refsect1>
7890<refsect1>
7891<title>LOCKING</title>
7892<para>
7893   Defined by the SCSI layer.  Might sleep.
7894</para>
7895</refsect1>
7896</refentry>
7897
7898<refentry id="API-ata-scsi-slave-config">
7899<refentryinfo>
7900 <title>LINUX</title>
7901 <productname>Kernel Hackers Manual</productname>
7902 <date>July 2017</date>
7903</refentryinfo>
7904<refmeta>
7905 <refentrytitle><phrase>ata_scsi_slave_config</phrase></refentrytitle>
7906 <manvolnum>9</manvolnum>
7907 <refmiscinfo class="version">4.1.27</refmiscinfo>
7908</refmeta>
7909<refnamediv>
7910 <refname>ata_scsi_slave_config</refname>
7911 <refpurpose>
7912     Set SCSI device attributes
7913 </refpurpose>
7914</refnamediv>
7915<refsynopsisdiv>
7916 <title>Synopsis</title>
7917  <funcsynopsis><funcprototype>
7918   <funcdef>int <function>ata_scsi_slave_config </function></funcdef>
7919   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
7920  </funcprototype></funcsynopsis>
7921</refsynopsisdiv>
7922<refsect1>
7923 <title>Arguments</title>
7924 <variablelist>
7925  <varlistentry>
7926   <term><parameter>sdev</parameter></term>
7927   <listitem>
7928    <para>
7929     SCSI device to examine
7930    </para>
7931   </listitem>
7932  </varlistentry>
7933 </variablelist>
7934</refsect1>
7935<refsect1>
7936<title>Description</title>
7937<para>
7938   This is called before we actually start reading
7939   and writing to the device, to configure certain
7940   SCSI mid-layer behaviors.
7941</para>
7942</refsect1>
7943<refsect1>
7944<title>LOCKING</title>
7945<para>
7946   Defined by SCSI layer.  We don't really care.
7947</para>
7948</refsect1>
7949</refentry>
7950
7951<refentry id="API-ata-scsi-slave-destroy">
7952<refentryinfo>
7953 <title>LINUX</title>
7954 <productname>Kernel Hackers Manual</productname>
7955 <date>July 2017</date>
7956</refentryinfo>
7957<refmeta>
7958 <refentrytitle><phrase>ata_scsi_slave_destroy</phrase></refentrytitle>
7959 <manvolnum>9</manvolnum>
7960 <refmiscinfo class="version">4.1.27</refmiscinfo>
7961</refmeta>
7962<refnamediv>
7963 <refname>ata_scsi_slave_destroy</refname>
7964 <refpurpose>
7965     SCSI device is about to be destroyed
7966 </refpurpose>
7967</refnamediv>
7968<refsynopsisdiv>
7969 <title>Synopsis</title>
7970  <funcsynopsis><funcprototype>
7971   <funcdef>void <function>ata_scsi_slave_destroy </function></funcdef>
7972   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
7973  </funcprototype></funcsynopsis>
7974</refsynopsisdiv>
7975<refsect1>
7976 <title>Arguments</title>
7977 <variablelist>
7978  <varlistentry>
7979   <term><parameter>sdev</parameter></term>
7980   <listitem>
7981    <para>
7982     SCSI device to be destroyed
7983    </para>
7984   </listitem>
7985  </varlistentry>
7986 </variablelist>
7987</refsect1>
7988<refsect1>
7989<title>Description</title>
7990<para>
7991   <parameter>sdev</parameter> is about to be destroyed for hot/warm unplugging.  If
7992   this unplugging was initiated by libata as indicated by NULL
7993   dev-&gt;sdev, this function doesn't have to do anything.
7994   Otherwise, SCSI layer initiated warm-unplug is in progress.
7995   Clear dev-&gt;sdev, schedule the device for ATA detach and invoke
7996   EH.
7997</para>
7998</refsect1>
7999<refsect1>
8000<title>LOCKING</title>
8001<para>
8002   Defined by SCSI layer.  We don't really care.
8003</para>
8004</refsect1>
8005</refentry>
8006
8007<refentry id="API---ata-change-queue-depth">
8008<refentryinfo>
8009 <title>LINUX</title>
8010 <productname>Kernel Hackers Manual</productname>
8011 <date>July 2017</date>
8012</refentryinfo>
8013<refmeta>
8014 <refentrytitle><phrase>__ata_change_queue_depth</phrase></refentrytitle>
8015 <manvolnum>9</manvolnum>
8016 <refmiscinfo class="version">4.1.27</refmiscinfo>
8017</refmeta>
8018<refnamediv>
8019 <refname>__ata_change_queue_depth</refname>
8020 <refpurpose>
8021     helper for ata_scsi_change_queue_depth
8022 </refpurpose>
8023</refnamediv>
8024<refsynopsisdiv>
8025 <title>Synopsis</title>
8026  <funcsynopsis><funcprototype>
8027   <funcdef>int <function>__ata_change_queue_depth </function></funcdef>
8028   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8029   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
8030   <paramdef>int <parameter>queue_depth</parameter></paramdef>
8031  </funcprototype></funcsynopsis>
8032</refsynopsisdiv>
8033<refsect1>
8034 <title>Arguments</title>
8035 <variablelist>
8036  <varlistentry>
8037   <term><parameter>ap</parameter></term>
8038   <listitem>
8039    <para>
8040     ATA port to which the device change the queue depth
8041    </para>
8042   </listitem>
8043  </varlistentry>
8044  <varlistentry>
8045   <term><parameter>sdev</parameter></term>
8046   <listitem>
8047    <para>
8048     SCSI device to configure queue depth for
8049    </para>
8050   </listitem>
8051  </varlistentry>
8052  <varlistentry>
8053   <term><parameter>queue_depth</parameter></term>
8054   <listitem>
8055    <para>
8056     new queue depth
8057    </para>
8058   </listitem>
8059  </varlistentry>
8060 </variablelist>
8061</refsect1>
8062<refsect1>
8063<title>Description</title>
8064<para>
8065   libsas and libata have different approaches for associating a sdev to
8066   its ata_port.
8067</para>
8068</refsect1>
8069</refentry>
8070
8071<refentry id="API-ata-scsi-change-queue-depth">
8072<refentryinfo>
8073 <title>LINUX</title>
8074 <productname>Kernel Hackers Manual</productname>
8075 <date>July 2017</date>
8076</refentryinfo>
8077<refmeta>
8078 <refentrytitle><phrase>ata_scsi_change_queue_depth</phrase></refentrytitle>
8079 <manvolnum>9</manvolnum>
8080 <refmiscinfo class="version">4.1.27</refmiscinfo>
8081</refmeta>
8082<refnamediv>
8083 <refname>ata_scsi_change_queue_depth</refname>
8084 <refpurpose>
8085     SCSI callback for queue depth config
8086 </refpurpose>
8087</refnamediv>
8088<refsynopsisdiv>
8089 <title>Synopsis</title>
8090  <funcsynopsis><funcprototype>
8091   <funcdef>int <function>ata_scsi_change_queue_depth </function></funcdef>
8092   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
8093   <paramdef>int <parameter>queue_depth</parameter></paramdef>
8094  </funcprototype></funcsynopsis>
8095</refsynopsisdiv>
8096<refsect1>
8097 <title>Arguments</title>
8098 <variablelist>
8099  <varlistentry>
8100   <term><parameter>sdev</parameter></term>
8101   <listitem>
8102    <para>
8103     SCSI device to configure queue depth for
8104    </para>
8105   </listitem>
8106  </varlistentry>
8107  <varlistentry>
8108   <term><parameter>queue_depth</parameter></term>
8109   <listitem>
8110    <para>
8111     new queue depth
8112    </para>
8113   </listitem>
8114  </varlistentry>
8115 </variablelist>
8116</refsect1>
8117<refsect1>
8118<title>Description</title>
8119<para>
8120   This is libata standard hostt-&gt;change_queue_depth callback.
8121   SCSI will call into this callback when user tries to set queue
8122   depth via sysfs.
8123</para>
8124</refsect1>
8125<refsect1>
8126<title>LOCKING</title>
8127<para>
8128   SCSI layer (we don't care)
8129</para>
8130</refsect1>
8131<refsect1>
8132<title>RETURNS</title>
8133<para>
8134   Newly configured queue depth.
8135</para>
8136</refsect1>
8137</refentry>
8138
8139<refentry id="API-ata-scsi-queuecmd">
8140<refentryinfo>
8141 <title>LINUX</title>
8142 <productname>Kernel Hackers Manual</productname>
8143 <date>July 2017</date>
8144</refentryinfo>
8145<refmeta>
8146 <refentrytitle><phrase>ata_scsi_queuecmd</phrase></refentrytitle>
8147 <manvolnum>9</manvolnum>
8148 <refmiscinfo class="version">4.1.27</refmiscinfo>
8149</refmeta>
8150<refnamediv>
8151 <refname>ata_scsi_queuecmd</refname>
8152 <refpurpose>
8153     Issue SCSI cdb to libata-managed device
8154 </refpurpose>
8155</refnamediv>
8156<refsynopsisdiv>
8157 <title>Synopsis</title>
8158  <funcsynopsis><funcprototype>
8159   <funcdef>int <function>ata_scsi_queuecmd </function></funcdef>
8160   <paramdef>struct Scsi_Host * <parameter>shost</parameter></paramdef>
8161   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
8162  </funcprototype></funcsynopsis>
8163</refsynopsisdiv>
8164<refsect1>
8165 <title>Arguments</title>
8166 <variablelist>
8167  <varlistentry>
8168   <term><parameter>shost</parameter></term>
8169   <listitem>
8170    <para>
8171     SCSI host of command to be sent
8172    </para>
8173   </listitem>
8174  </varlistentry>
8175  <varlistentry>
8176   <term><parameter>cmd</parameter></term>
8177   <listitem>
8178    <para>
8179     SCSI command to be sent
8180    </para>
8181   </listitem>
8182  </varlistentry>
8183 </variablelist>
8184</refsect1>
8185<refsect1>
8186<title>Description</title>
8187<para>
8188   In some cases, this function translates SCSI commands into
8189   ATA taskfiles, and queues the taskfiles to be sent to
8190   hardware.  In other cases, this function simulates a
8191   SCSI device by evaluating and responding to certain
8192   SCSI commands.  This creates the overall effect of
8193   ATA and ATAPI devices appearing as SCSI devices.
8194</para>
8195</refsect1>
8196<refsect1>
8197<title>LOCKING</title>
8198<para>
8199   ATA host lock
8200</para>
8201</refsect1>
8202<refsect1>
8203<title>RETURNS</title>
8204<para>
8205   Return value from <function>__ata_scsi_queuecmd</function> if <parameter>cmd</parameter> can be queued,
8206   0 otherwise.
8207</para>
8208</refsect1>
8209</refentry>
8210
8211<refentry id="API-ata-scsi-simulate">
8212<refentryinfo>
8213 <title>LINUX</title>
8214 <productname>Kernel Hackers Manual</productname>
8215 <date>July 2017</date>
8216</refentryinfo>
8217<refmeta>
8218 <refentrytitle><phrase>ata_scsi_simulate</phrase></refentrytitle>
8219 <manvolnum>9</manvolnum>
8220 <refmiscinfo class="version">4.1.27</refmiscinfo>
8221</refmeta>
8222<refnamediv>
8223 <refname>ata_scsi_simulate</refname>
8224 <refpurpose>
8225     simulate SCSI command on ATA device
8226 </refpurpose>
8227</refnamediv>
8228<refsynopsisdiv>
8229 <title>Synopsis</title>
8230  <funcsynopsis><funcprototype>
8231   <funcdef>void <function>ata_scsi_simulate </function></funcdef>
8232   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
8233   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
8234  </funcprototype></funcsynopsis>
8235</refsynopsisdiv>
8236<refsect1>
8237 <title>Arguments</title>
8238 <variablelist>
8239  <varlistentry>
8240   <term><parameter>dev</parameter></term>
8241   <listitem>
8242    <para>
8243     the target device
8244    </para>
8245   </listitem>
8246  </varlistentry>
8247  <varlistentry>
8248   <term><parameter>cmd</parameter></term>
8249   <listitem>
8250    <para>
8251     SCSI command being sent to device.
8252    </para>
8253   </listitem>
8254  </varlistentry>
8255 </variablelist>
8256</refsect1>
8257<refsect1>
8258<title>Description</title>
8259<para>
8260   Interprets and directly executes a select list of SCSI commands
8261   that can be handled internally.
8262</para>
8263</refsect1>
8264<refsect1>
8265<title>LOCKING</title>
8266<para>
8267   spin_lock_irqsave(host lock)
8268</para>
8269</refsect1>
8270</refentry>
8271
8272<refentry id="API-ata-sas-port-alloc">
8273<refentryinfo>
8274 <title>LINUX</title>
8275 <productname>Kernel Hackers Manual</productname>
8276 <date>July 2017</date>
8277</refentryinfo>
8278<refmeta>
8279 <refentrytitle><phrase>ata_sas_port_alloc</phrase></refentrytitle>
8280 <manvolnum>9</manvolnum>
8281 <refmiscinfo class="version">4.1.27</refmiscinfo>
8282</refmeta>
8283<refnamediv>
8284 <refname>ata_sas_port_alloc</refname>
8285 <refpurpose>
8286     Allocate port for a SAS attached SATA device
8287 </refpurpose>
8288</refnamediv>
8289<refsynopsisdiv>
8290 <title>Synopsis</title>
8291  <funcsynopsis><funcprototype>
8292   <funcdef>struct ata_port * <function>ata_sas_port_alloc </function></funcdef>
8293   <paramdef>struct ata_host * <parameter>host</parameter></paramdef>
8294   <paramdef>struct ata_port_info * <parameter>port_info</parameter></paramdef>
8295   <paramdef>struct Scsi_Host * <parameter>shost</parameter></paramdef>
8296  </funcprototype></funcsynopsis>
8297</refsynopsisdiv>
8298<refsect1>
8299 <title>Arguments</title>
8300 <variablelist>
8301  <varlistentry>
8302   <term><parameter>host</parameter></term>
8303   <listitem>
8304    <para>
8305     ATA host container for all SAS ports
8306    </para>
8307   </listitem>
8308  </varlistentry>
8309  <varlistentry>
8310   <term><parameter>port_info</parameter></term>
8311   <listitem>
8312    <para>
8313     Information from low-level host driver
8314    </para>
8315   </listitem>
8316  </varlistentry>
8317  <varlistentry>
8318   <term><parameter>shost</parameter></term>
8319   <listitem>
8320    <para>
8321     SCSI host that the scsi device is attached to
8322    </para>
8323   </listitem>
8324  </varlistentry>
8325 </variablelist>
8326</refsect1>
8327<refsect1>
8328<title>LOCKING</title>
8329<para>
8330   PCI/etc. bus probe sem.
8331</para>
8332</refsect1>
8333<refsect1>
8334<title>RETURNS</title>
8335<para>
8336   ata_port pointer on success / NULL on failure.
8337</para>
8338</refsect1>
8339</refentry>
8340
8341<refentry id="API-ata-sas-port-start">
8342<refentryinfo>
8343 <title>LINUX</title>
8344 <productname>Kernel Hackers Manual</productname>
8345 <date>July 2017</date>
8346</refentryinfo>
8347<refmeta>
8348 <refentrytitle><phrase>ata_sas_port_start</phrase></refentrytitle>
8349 <manvolnum>9</manvolnum>
8350 <refmiscinfo class="version">4.1.27</refmiscinfo>
8351</refmeta>
8352<refnamediv>
8353 <refname>ata_sas_port_start</refname>
8354 <refpurpose>
8355     Set port up for dma.
8356 </refpurpose>
8357</refnamediv>
8358<refsynopsisdiv>
8359 <title>Synopsis</title>
8360  <funcsynopsis><funcprototype>
8361   <funcdef>int <function>ata_sas_port_start </function></funcdef>
8362   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8363  </funcprototype></funcsynopsis>
8364</refsynopsisdiv>
8365<refsect1>
8366 <title>Arguments</title>
8367 <variablelist>
8368  <varlistentry>
8369   <term><parameter>ap</parameter></term>
8370   <listitem>
8371    <para>
8372     Port to initialize
8373    </para>
8374   </listitem>
8375  </varlistentry>
8376 </variablelist>
8377</refsect1>
8378<refsect1>
8379<title>Description</title>
8380<para>
8381   Called just after data structures for each port are
8382   initialized.
8383   </para><para>
8384
8385   May be used as the <function>port_start</function> entry in ata_port_operations.
8386</para>
8387</refsect1>
8388<refsect1>
8389<title>LOCKING</title>
8390<para>
8391   Inherited from caller.
8392</para>
8393</refsect1>
8394</refentry>
8395
8396<refentry id="API-ata-sas-port-stop">
8397<refentryinfo>
8398 <title>LINUX</title>
8399 <productname>Kernel Hackers Manual</productname>
8400 <date>July 2017</date>
8401</refentryinfo>
8402<refmeta>
8403 <refentrytitle><phrase>ata_sas_port_stop</phrase></refentrytitle>
8404 <manvolnum>9</manvolnum>
8405 <refmiscinfo class="version">4.1.27</refmiscinfo>
8406</refmeta>
8407<refnamediv>
8408 <refname>ata_sas_port_stop</refname>
8409 <refpurpose>
8410     Undo <function>ata_sas_port_start</function>
8411 </refpurpose>
8412</refnamediv>
8413<refsynopsisdiv>
8414 <title>Synopsis</title>
8415  <funcsynopsis><funcprototype>
8416   <funcdef>void <function>ata_sas_port_stop </function></funcdef>
8417   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8418  </funcprototype></funcsynopsis>
8419</refsynopsisdiv>
8420<refsect1>
8421 <title>Arguments</title>
8422 <variablelist>
8423  <varlistentry>
8424   <term><parameter>ap</parameter></term>
8425   <listitem>
8426    <para>
8427     Port to shut down
8428    </para>
8429   </listitem>
8430  </varlistentry>
8431 </variablelist>
8432</refsect1>
8433<refsect1>
8434<title>Description</title>
8435<para>
8436   May be used as the <function>port_stop</function> entry in ata_port_operations.
8437</para>
8438</refsect1>
8439<refsect1>
8440<title>LOCKING</title>
8441<para>
8442   Inherited from caller.
8443</para>
8444</refsect1>
8445</refentry>
8446
8447<refentry id="API-ata-sas-async-probe">
8448<refentryinfo>
8449 <title>LINUX</title>
8450 <productname>Kernel Hackers Manual</productname>
8451 <date>July 2017</date>
8452</refentryinfo>
8453<refmeta>
8454 <refentrytitle><phrase>ata_sas_async_probe</phrase></refentrytitle>
8455 <manvolnum>9</manvolnum>
8456 <refmiscinfo class="version">4.1.27</refmiscinfo>
8457</refmeta>
8458<refnamediv>
8459 <refname>ata_sas_async_probe</refname>
8460 <refpurpose>
8461     simply schedule probing and return
8462 </refpurpose>
8463</refnamediv>
8464<refsynopsisdiv>
8465 <title>Synopsis</title>
8466  <funcsynopsis><funcprototype>
8467   <funcdef>void <function>ata_sas_async_probe </function></funcdef>
8468   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8469  </funcprototype></funcsynopsis>
8470</refsynopsisdiv>
8471<refsect1>
8472 <title>Arguments</title>
8473 <variablelist>
8474  <varlistentry>
8475   <term><parameter>ap</parameter></term>
8476   <listitem>
8477    <para>
8478     Port to probe
8479    </para>
8480   </listitem>
8481  </varlistentry>
8482 </variablelist>
8483</refsect1>
8484<refsect1>
8485<title>Description</title>
8486<para>
8487   For batch scheduling of probe for sas attached ata devices, assumes
8488   the port has already been through <function>ata_sas_port_init</function>
8489</para>
8490</refsect1>
8491</refentry>
8492
8493<refentry id="API-ata-sas-port-init">
8494<refentryinfo>
8495 <title>LINUX</title>
8496 <productname>Kernel Hackers Manual</productname>
8497 <date>July 2017</date>
8498</refentryinfo>
8499<refmeta>
8500 <refentrytitle><phrase>ata_sas_port_init</phrase></refentrytitle>
8501 <manvolnum>9</manvolnum>
8502 <refmiscinfo class="version">4.1.27</refmiscinfo>
8503</refmeta>
8504<refnamediv>
8505 <refname>ata_sas_port_init</refname>
8506 <refpurpose>
8507     Initialize a SATA device
8508 </refpurpose>
8509</refnamediv>
8510<refsynopsisdiv>
8511 <title>Synopsis</title>
8512  <funcsynopsis><funcprototype>
8513   <funcdef>int <function>ata_sas_port_init </function></funcdef>
8514   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8515  </funcprototype></funcsynopsis>
8516</refsynopsisdiv>
8517<refsect1>
8518 <title>Arguments</title>
8519 <variablelist>
8520  <varlistentry>
8521   <term><parameter>ap</parameter></term>
8522   <listitem>
8523    <para>
8524     SATA port to initialize
8525    </para>
8526   </listitem>
8527  </varlistentry>
8528 </variablelist>
8529</refsect1>
8530<refsect1>
8531<title>LOCKING</title>
8532<para>
8533   PCI/etc. bus probe sem.
8534</para>
8535</refsect1>
8536<refsect1>
8537<title>RETURNS</title>
8538<para>
8539   Zero on success, non-zero on error.
8540</para>
8541</refsect1>
8542</refentry>
8543
8544<refentry id="API-ata-sas-port-destroy">
8545<refentryinfo>
8546 <title>LINUX</title>
8547 <productname>Kernel Hackers Manual</productname>
8548 <date>July 2017</date>
8549</refentryinfo>
8550<refmeta>
8551 <refentrytitle><phrase>ata_sas_port_destroy</phrase></refentrytitle>
8552 <manvolnum>9</manvolnum>
8553 <refmiscinfo class="version">4.1.27</refmiscinfo>
8554</refmeta>
8555<refnamediv>
8556 <refname>ata_sas_port_destroy</refname>
8557 <refpurpose>
8558     Destroy a SATA port allocated by ata_sas_port_alloc
8559 </refpurpose>
8560</refnamediv>
8561<refsynopsisdiv>
8562 <title>Synopsis</title>
8563  <funcsynopsis><funcprototype>
8564   <funcdef>void <function>ata_sas_port_destroy </function></funcdef>
8565   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8566  </funcprototype></funcsynopsis>
8567</refsynopsisdiv>
8568<refsect1>
8569 <title>Arguments</title>
8570 <variablelist>
8571  <varlistentry>
8572   <term><parameter>ap</parameter></term>
8573   <listitem>
8574    <para>
8575     SATA port to destroy
8576    </para>
8577   </listitem>
8578  </varlistentry>
8579 </variablelist>
8580</refsect1>
8581</refentry>
8582
8583<refentry id="API-ata-sas-slave-configure">
8584<refentryinfo>
8585 <title>LINUX</title>
8586 <productname>Kernel Hackers Manual</productname>
8587 <date>July 2017</date>
8588</refentryinfo>
8589<refmeta>
8590 <refentrytitle><phrase>ata_sas_slave_configure</phrase></refentrytitle>
8591 <manvolnum>9</manvolnum>
8592 <refmiscinfo class="version">4.1.27</refmiscinfo>
8593</refmeta>
8594<refnamediv>
8595 <refname>ata_sas_slave_configure</refname>
8596 <refpurpose>
8597     Default slave_config routine for libata devices
8598 </refpurpose>
8599</refnamediv>
8600<refsynopsisdiv>
8601 <title>Synopsis</title>
8602  <funcsynopsis><funcprototype>
8603   <funcdef>int <function>ata_sas_slave_configure </function></funcdef>
8604   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
8605   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8606  </funcprototype></funcsynopsis>
8607</refsynopsisdiv>
8608<refsect1>
8609 <title>Arguments</title>
8610 <variablelist>
8611  <varlistentry>
8612   <term><parameter>sdev</parameter></term>
8613   <listitem>
8614    <para>
8615     SCSI device to configure
8616    </para>
8617   </listitem>
8618  </varlistentry>
8619  <varlistentry>
8620   <term><parameter>ap</parameter></term>
8621   <listitem>
8622    <para>
8623     ATA port to which SCSI device is attached
8624    </para>
8625   </listitem>
8626  </varlistentry>
8627 </variablelist>
8628</refsect1>
8629<refsect1>
8630<title>RETURNS</title>
8631<para>
8632   Zero.
8633</para>
8634</refsect1>
8635</refentry>
8636
8637<refentry id="API-ata-sas-queuecmd">
8638<refentryinfo>
8639 <title>LINUX</title>
8640 <productname>Kernel Hackers Manual</productname>
8641 <date>July 2017</date>
8642</refentryinfo>
8643<refmeta>
8644 <refentrytitle><phrase>ata_sas_queuecmd</phrase></refentrytitle>
8645 <manvolnum>9</manvolnum>
8646 <refmiscinfo class="version">4.1.27</refmiscinfo>
8647</refmeta>
8648<refnamediv>
8649 <refname>ata_sas_queuecmd</refname>
8650 <refpurpose>
8651     Issue SCSI cdb to libata-managed device
8652 </refpurpose>
8653</refnamediv>
8654<refsynopsisdiv>
8655 <title>Synopsis</title>
8656  <funcsynopsis><funcprototype>
8657   <funcdef>int <function>ata_sas_queuecmd </function></funcdef>
8658   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
8659   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8660  </funcprototype></funcsynopsis>
8661</refsynopsisdiv>
8662<refsect1>
8663 <title>Arguments</title>
8664 <variablelist>
8665  <varlistentry>
8666   <term><parameter>cmd</parameter></term>
8667   <listitem>
8668    <para>
8669     SCSI command to be sent
8670    </para>
8671   </listitem>
8672  </varlistentry>
8673  <varlistentry>
8674   <term><parameter>ap</parameter></term>
8675   <listitem>
8676    <para>
8677     ATA port to which the command is being sent
8678    </para>
8679   </listitem>
8680  </varlistentry>
8681 </variablelist>
8682</refsect1>
8683<refsect1>
8684<title>RETURNS</title>
8685<para>
8686   Return value from <function>__ata_scsi_queuecmd</function> if <parameter>cmd</parameter> can be queued,
8687   0 otherwise.
8688</para>
8689</refsect1>
8690</refentry>
8691
8692<!-- drivers/ata/libata-scsi.c -->
8693<refentry id="API-ata-get-identity">
8694<refentryinfo>
8695 <title>LINUX</title>
8696 <productname>Kernel Hackers Manual</productname>
8697 <date>July 2017</date>
8698</refentryinfo>
8699<refmeta>
8700 <refentrytitle><phrase>ata_get_identity</phrase></refentrytitle>
8701 <manvolnum>9</manvolnum>
8702 <refmiscinfo class="version">4.1.27</refmiscinfo>
8703</refmeta>
8704<refnamediv>
8705 <refname>ata_get_identity</refname>
8706 <refpurpose>
8707  Handler for HDIO_GET_IDENTITY ioctl
8708 </refpurpose>
8709</refnamediv>
8710<refsynopsisdiv>
8711 <title>Synopsis</title>
8712  <funcsynopsis><funcprototype>
8713   <funcdef>int <function>ata_get_identity </function></funcdef>
8714   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
8715   <paramdef>struct scsi_device * <parameter>sdev</parameter></paramdef>
8716   <paramdef>void __user * <parameter>arg</parameter></paramdef>
8717  </funcprototype></funcsynopsis>
8718</refsynopsisdiv>
8719<refsect1>
8720 <title>Arguments</title>
8721 <variablelist>
8722  <varlistentry>
8723   <term><parameter>ap</parameter></term>
8724   <listitem>
8725    <para>
8726     target port
8727    </para>
8728   </listitem>
8729  </varlistentry>
8730  <varlistentry>
8731   <term><parameter>sdev</parameter></term>
8732   <listitem>
8733    <para>
8734     SCSI device to get identify data for
8735    </para>
8736   </listitem>
8737  </varlistentry>
8738  <varlistentry>
8739   <term><parameter>arg</parameter></term>
8740   <listitem>
8741    <para>
8742     User buffer area for identify data
8743    </para>
8744   </listitem>
8745  </varlistentry>
8746 </variablelist>
8747</refsect1>
8748<refsect1>
8749<title>LOCKING</title>
8750<para>
8751   Defined by the SCSI layer.  We don't really care.
8752</para>
8753</refsect1>
8754<refsect1>
8755<title>RETURNS</title>
8756<para>
8757   Zero on success, negative errno on error.
8758</para>
8759</refsect1>
8760</refentry>
8761
8762<refentry id="API-ata-cmd-ioctl">
8763<refentryinfo>
8764 <title>LINUX</title>
8765 <productname>Kernel Hackers Manual</productname>
8766 <date>July 2017</date>
8767</refentryinfo>
8768<refmeta>
8769 <refentrytitle><phrase>ata_cmd_ioctl</phrase></refentrytitle>
8770 <manvolnum>9</manvolnum>
8771 <refmiscinfo class="version">4.1.27</refmiscinfo>
8772</refmeta>
8773<refnamediv>
8774 <refname>ata_cmd_ioctl</refname>
8775 <refpurpose>
8776     Handler for HDIO_DRIVE_CMD ioctl
8777 </refpurpose>
8778</refnamediv>
8779<refsynopsisdiv>
8780 <title>Synopsis</title>
8781  <funcsynopsis><funcprototype>
8782   <funcdef>int <function>ata_cmd_ioctl </function></funcdef>
8783   <paramdef>struct scsi_device * <parameter>scsidev</parameter></paramdef>
8784   <paramdef>void __user * <parameter>arg</parameter></paramdef>
8785  </funcprototype></funcsynopsis>
8786</refsynopsisdiv>
8787<refsect1>
8788 <title>Arguments</title>
8789 <variablelist>
8790  <varlistentry>
8791   <term><parameter>scsidev</parameter></term>
8792   <listitem>
8793    <para>
8794     Device to which we are issuing command
8795    </para>
8796   </listitem>
8797  </varlistentry>
8798  <varlistentry>
8799   <term><parameter>arg</parameter></term>
8800   <listitem>
8801    <para>
8802     User provided data for issuing command
8803    </para>
8804   </listitem>
8805  </varlistentry>
8806 </variablelist>
8807</refsect1>
8808<refsect1>
8809<title>LOCKING</title>
8810<para>
8811   Defined by the SCSI layer.  We don't really care.
8812</para>
8813</refsect1>
8814<refsect1>
8815<title>RETURNS</title>
8816<para>
8817   Zero on success, negative errno on error.
8818</para>
8819</refsect1>
8820</refentry>
8821
8822<refentry id="API-ata-task-ioctl">
8823<refentryinfo>
8824 <title>LINUX</title>
8825 <productname>Kernel Hackers Manual</productname>
8826 <date>July 2017</date>
8827</refentryinfo>
8828<refmeta>
8829 <refentrytitle><phrase>ata_task_ioctl</phrase></refentrytitle>
8830 <manvolnum>9</manvolnum>
8831 <refmiscinfo class="version">4.1.27</refmiscinfo>
8832</refmeta>
8833<refnamediv>
8834 <refname>ata_task_ioctl</refname>
8835 <refpurpose>
8836     Handler for HDIO_DRIVE_TASK ioctl
8837 </refpurpose>
8838</refnamediv>
8839<refsynopsisdiv>
8840 <title>Synopsis</title>
8841  <funcsynopsis><funcprototype>
8842   <funcdef>int <function>ata_task_ioctl </function></funcdef>
8843   <paramdef>struct scsi_device * <parameter>scsidev</parameter></paramdef>
8844   <paramdef>void __user * <parameter>arg</parameter></paramdef>
8845  </funcprototype></funcsynopsis>
8846</refsynopsisdiv>
8847<refsect1>
8848 <title>Arguments</title>
8849 <variablelist>
8850  <varlistentry>
8851   <term><parameter>scsidev</parameter></term>
8852   <listitem>
8853    <para>
8854     Device to which we are issuing command
8855    </para>
8856   </listitem>
8857  </varlistentry>
8858  <varlistentry>
8859   <term><parameter>arg</parameter></term>
8860   <listitem>
8861    <para>
8862     User provided data for issuing command
8863    </para>
8864   </listitem>
8865  </varlistentry>
8866 </variablelist>
8867</refsect1>
8868<refsect1>
8869<title>LOCKING</title>
8870<para>
8871   Defined by the SCSI layer.  We don't really care.
8872</para>
8873</refsect1>
8874<refsect1>
8875<title>RETURNS</title>
8876<para>
8877   Zero on success, negative errno on error.
8878</para>
8879</refsect1>
8880</refentry>
8881
8882<refentry id="API-ata-scsi-qc-new">
8883<refentryinfo>
8884 <title>LINUX</title>
8885 <productname>Kernel Hackers Manual</productname>
8886 <date>July 2017</date>
8887</refentryinfo>
8888<refmeta>
8889 <refentrytitle><phrase>ata_scsi_qc_new</phrase></refentrytitle>
8890 <manvolnum>9</manvolnum>
8891 <refmiscinfo class="version">4.1.27</refmiscinfo>
8892</refmeta>
8893<refnamediv>
8894 <refname>ata_scsi_qc_new</refname>
8895 <refpurpose>
8896     acquire new ata_queued_cmd reference
8897 </refpurpose>
8898</refnamediv>
8899<refsynopsisdiv>
8900 <title>Synopsis</title>
8901  <funcsynopsis><funcprototype>
8902   <funcdef>struct ata_queued_cmd * <function>ata_scsi_qc_new </function></funcdef>
8903   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
8904   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
8905  </funcprototype></funcsynopsis>
8906</refsynopsisdiv>
8907<refsect1>
8908 <title>Arguments</title>
8909 <variablelist>
8910  <varlistentry>
8911   <term><parameter>dev</parameter></term>
8912   <listitem>
8913    <para>
8914     ATA device to which the new command is attached
8915    </para>
8916   </listitem>
8917  </varlistentry>
8918  <varlistentry>
8919   <term><parameter>cmd</parameter></term>
8920   <listitem>
8921    <para>
8922     SCSI command that originated this ATA command
8923    </para>
8924   </listitem>
8925  </varlistentry>
8926 </variablelist>
8927</refsect1>
8928<refsect1>
8929<title>Description</title>
8930<para>
8931   Obtain a reference to an unused ata_queued_cmd structure,
8932   which is the basic libata structure representing a single
8933   ATA command sent to the hardware.
8934   </para><para>
8935
8936   If a command was available, fill in the SCSI-specific
8937   portions of the structure with information on the
8938   current command.
8939</para>
8940</refsect1>
8941<refsect1>
8942<title>LOCKING</title>
8943<para>
8944   spin_lock_irqsave(host lock)
8945</para>
8946</refsect1>
8947<refsect1>
8948<title>RETURNS</title>
8949<para>
8950   Command allocated, or <constant>NULL</constant> if none available.
8951</para>
8952</refsect1>
8953</refentry>
8954
8955<refentry id="API-ata-dump-status">
8956<refentryinfo>
8957 <title>LINUX</title>
8958 <productname>Kernel Hackers Manual</productname>
8959 <date>July 2017</date>
8960</refentryinfo>
8961<refmeta>
8962 <refentrytitle><phrase>ata_dump_status</phrase></refentrytitle>
8963 <manvolnum>9</manvolnum>
8964 <refmiscinfo class="version">4.1.27</refmiscinfo>
8965</refmeta>
8966<refnamediv>
8967 <refname>ata_dump_status</refname>
8968 <refpurpose>
8969     user friendly display of error info
8970 </refpurpose>
8971</refnamediv>
8972<refsynopsisdiv>
8973 <title>Synopsis</title>
8974  <funcsynopsis><funcprototype>
8975   <funcdef>void <function>ata_dump_status </function></funcdef>
8976   <paramdef>unsigned <parameter>id</parameter></paramdef>
8977   <paramdef>struct ata_taskfile * <parameter>tf</parameter></paramdef>
8978  </funcprototype></funcsynopsis>
8979</refsynopsisdiv>
8980<refsect1>
8981 <title>Arguments</title>
8982 <variablelist>
8983  <varlistentry>
8984   <term><parameter>id</parameter></term>
8985   <listitem>
8986    <para>
8987     id of the port in question
8988    </para>
8989   </listitem>
8990  </varlistentry>
8991  <varlistentry>
8992   <term><parameter>tf</parameter></term>
8993   <listitem>
8994    <para>
8995     ptr to filled out taskfile
8996    </para>
8997   </listitem>
8998  </varlistentry>
8999 </variablelist>
9000</refsect1>
9001<refsect1>
9002<title>Description</title>
9003<para>
9004   Decode and dump the ATA error/status registers for the user so
9005   that they have some idea what really happened at the non
9006   make-believe layer.
9007</para>
9008</refsect1>
9009<refsect1>
9010<title>LOCKING</title>
9011<para>
9012   inherited from caller
9013</para>
9014</refsect1>
9015</refentry>
9016
9017<refentry id="API-ata-to-sense-error">
9018<refentryinfo>
9019 <title>LINUX</title>
9020 <productname>Kernel Hackers Manual</productname>
9021 <date>July 2017</date>
9022</refentryinfo>
9023<refmeta>
9024 <refentrytitle><phrase>ata_to_sense_error</phrase></refentrytitle>
9025 <manvolnum>9</manvolnum>
9026 <refmiscinfo class="version">4.1.27</refmiscinfo>
9027</refmeta>
9028<refnamediv>
9029 <refname>ata_to_sense_error</refname>
9030 <refpurpose>
9031     convert ATA error to SCSI error
9032 </refpurpose>
9033</refnamediv>
9034<refsynopsisdiv>
9035 <title>Synopsis</title>
9036  <funcsynopsis><funcprototype>
9037   <funcdef>void <function>ata_to_sense_error </function></funcdef>
9038   <paramdef>unsigned <parameter>id</parameter></paramdef>
9039   <paramdef>u8 <parameter>drv_stat</parameter></paramdef>
9040   <paramdef>u8 <parameter>drv_err</parameter></paramdef>
9041   <paramdef>u8 * <parameter>sk</parameter></paramdef>
9042   <paramdef>u8 * <parameter>asc</parameter></paramdef>
9043   <paramdef>u8 * <parameter>ascq</parameter></paramdef>
9044   <paramdef>int <parameter>verbose</parameter></paramdef>
9045  </funcprototype></funcsynopsis>
9046</refsynopsisdiv>
9047<refsect1>
9048 <title>Arguments</title>
9049 <variablelist>
9050  <varlistentry>
9051   <term><parameter>id</parameter></term>
9052   <listitem>
9053    <para>
9054     ATA device number
9055    </para>
9056   </listitem>
9057  </varlistentry>
9058  <varlistentry>
9059   <term><parameter>drv_stat</parameter></term>
9060   <listitem>
9061    <para>
9062     value contained in ATA status register
9063    </para>
9064   </listitem>
9065  </varlistentry>
9066  <varlistentry>
9067   <term><parameter>drv_err</parameter></term>
9068   <listitem>
9069    <para>
9070     value contained in ATA error register
9071    </para>
9072   </listitem>
9073  </varlistentry>
9074  <varlistentry>
9075   <term><parameter>sk</parameter></term>
9076   <listitem>
9077    <para>
9078     the sense key we'll fill out
9079    </para>
9080   </listitem>
9081  </varlistentry>
9082  <varlistentry>
9083   <term><parameter>asc</parameter></term>
9084   <listitem>
9085    <para>
9086     the additional sense code we'll fill out
9087    </para>
9088   </listitem>
9089  </varlistentry>
9090  <varlistentry>
9091   <term><parameter>ascq</parameter></term>
9092   <listitem>
9093    <para>
9094     the additional sense code qualifier we'll fill out
9095    </para>
9096   </listitem>
9097  </varlistentry>
9098  <varlistentry>
9099   <term><parameter>verbose</parameter></term>
9100   <listitem>
9101    <para>
9102     be verbose
9103    </para>
9104   </listitem>
9105  </varlistentry>
9106 </variablelist>
9107</refsect1>
9108<refsect1>
9109<title>Description</title>
9110<para>
9111   Converts an ATA error into a SCSI error.  Fill out pointers to
9112   SK, ASC, and ASCQ bytes for later use in fixed or descriptor
9113   format sense blocks.
9114</para>
9115</refsect1>
9116<refsect1>
9117<title>LOCKING</title>
9118<para>
9119   spin_lock_irqsave(host lock)
9120</para>
9121</refsect1>
9122</refentry>
9123
9124<refentry id="API-ata-gen-ata-sense">
9125<refentryinfo>
9126 <title>LINUX</title>
9127 <productname>Kernel Hackers Manual</productname>
9128 <date>July 2017</date>
9129</refentryinfo>
9130<refmeta>
9131 <refentrytitle><phrase>ata_gen_ata_sense</phrase></refentrytitle>
9132 <manvolnum>9</manvolnum>
9133 <refmiscinfo class="version">4.1.27</refmiscinfo>
9134</refmeta>
9135<refnamediv>
9136 <refname>ata_gen_ata_sense</refname>
9137 <refpurpose>
9138     generate a SCSI fixed sense block
9139 </refpurpose>
9140</refnamediv>
9141<refsynopsisdiv>
9142 <title>Synopsis</title>
9143  <funcsynopsis><funcprototype>
9144   <funcdef>void <function>ata_gen_ata_sense </function></funcdef>
9145   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
9146  </funcprototype></funcsynopsis>
9147</refsynopsisdiv>
9148<refsect1>
9149 <title>Arguments</title>
9150 <variablelist>
9151  <varlistentry>
9152   <term><parameter>qc</parameter></term>
9153   <listitem>
9154    <para>
9155     Command that we are erroring out
9156    </para>
9157   </listitem>
9158  </varlistentry>
9159 </variablelist>
9160</refsect1>
9161<refsect1>
9162<title>Description</title>
9163<para>
9164   Generate sense block for a failed ATA command <parameter>qc</parameter>.  Descriptor
9165   format is used to accommodate LBA48 block address.
9166</para>
9167</refsect1>
9168<refsect1>
9169<title>LOCKING</title>
9170<para>
9171   None.
9172</para>
9173</refsect1>
9174</refentry>
9175
9176<refentry id="API-atapi-drain-needed">
9177<refentryinfo>
9178 <title>LINUX</title>
9179 <productname>Kernel Hackers Manual</productname>
9180 <date>July 2017</date>
9181</refentryinfo>
9182<refmeta>
9183 <refentrytitle><phrase>atapi_drain_needed</phrase></refentrytitle>
9184 <manvolnum>9</manvolnum>
9185 <refmiscinfo class="version">4.1.27</refmiscinfo>
9186</refmeta>
9187<refnamediv>
9188 <refname>atapi_drain_needed</refname>
9189 <refpurpose>
9190     Check whether data transfer may overflow
9191 </refpurpose>
9192</refnamediv>
9193<refsynopsisdiv>
9194 <title>Synopsis</title>
9195  <funcsynopsis><funcprototype>
9196   <funcdef>int <function>atapi_drain_needed </function></funcdef>
9197   <paramdef>struct request * <parameter>rq</parameter></paramdef>
9198  </funcprototype></funcsynopsis>
9199</refsynopsisdiv>
9200<refsect1>
9201 <title>Arguments</title>
9202 <variablelist>
9203  <varlistentry>
9204   <term><parameter>rq</parameter></term>
9205   <listitem>
9206    <para>
9207     request to be checked
9208    </para>
9209   </listitem>
9210  </varlistentry>
9211 </variablelist>
9212</refsect1>
9213<refsect1>
9214<title>Description</title>
9215<para>
9216   ATAPI commands which transfer variable length data to host
9217   might overflow due to application error or hardare bug.  This
9218   function checks whether overflow should be drained and ignored
9219   for <parameter>request</parameter>.
9220</para>
9221</refsect1>
9222<refsect1>
9223<title>LOCKING</title>
9224<para>
9225   None.
9226</para>
9227</refsect1>
9228<refsect1>
9229<title>RETURNS</title>
9230<para>
9231   1 if ; otherwise, 0.
9232</para>
9233</refsect1>
9234</refentry>
9235
9236<refentry id="API-ata-scsi-start-stop-xlat">
9237<refentryinfo>
9238 <title>LINUX</title>
9239 <productname>Kernel Hackers Manual</productname>
9240 <date>July 2017</date>
9241</refentryinfo>
9242<refmeta>
9243 <refentrytitle><phrase>ata_scsi_start_stop_xlat</phrase></refentrytitle>
9244 <manvolnum>9</manvolnum>
9245 <refmiscinfo class="version">4.1.27</refmiscinfo>
9246</refmeta>
9247<refnamediv>
9248 <refname>ata_scsi_start_stop_xlat</refname>
9249 <refpurpose>
9250     Translate SCSI START STOP UNIT command
9251 </refpurpose>
9252</refnamediv>
9253<refsynopsisdiv>
9254 <title>Synopsis</title>
9255  <funcsynopsis><funcprototype>
9256   <funcdef>unsigned int <function>ata_scsi_start_stop_xlat </function></funcdef>
9257   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
9258  </funcprototype></funcsynopsis>
9259</refsynopsisdiv>
9260<refsect1>
9261 <title>Arguments</title>
9262 <variablelist>
9263  <varlistentry>
9264   <term><parameter>qc</parameter></term>
9265   <listitem>
9266    <para>
9267     Storage for translated ATA taskfile
9268    </para>
9269   </listitem>
9270  </varlistentry>
9271 </variablelist>
9272</refsect1>
9273<refsect1>
9274<title>Description</title>
9275<para>
9276   Sets up an ATA taskfile to issue STANDBY (to stop) or READ VERIFY
9277   (to start). Perhaps these commands should be preceded by
9278   CHECK POWER MODE to see what power mode the device is already in.
9279   [See SAT revision 5 at www.t10.org]
9280</para>
9281</refsect1>
9282<refsect1>
9283<title>LOCKING</title>
9284<para>
9285   spin_lock_irqsave(host lock)
9286</para>
9287</refsect1>
9288<refsect1>
9289<title>RETURNS</title>
9290<para>
9291   Zero on success, non-zero on error.
9292</para>
9293</refsect1>
9294</refentry>
9295
9296<refentry id="API-ata-scsi-flush-xlat">
9297<refentryinfo>
9298 <title>LINUX</title>
9299 <productname>Kernel Hackers Manual</productname>
9300 <date>July 2017</date>
9301</refentryinfo>
9302<refmeta>
9303 <refentrytitle><phrase>ata_scsi_flush_xlat</phrase></refentrytitle>
9304 <manvolnum>9</manvolnum>
9305 <refmiscinfo class="version">4.1.27</refmiscinfo>
9306</refmeta>
9307<refnamediv>
9308 <refname>ata_scsi_flush_xlat</refname>
9309 <refpurpose>
9310     Translate SCSI SYNCHRONIZE CACHE command
9311 </refpurpose>
9312</refnamediv>
9313<refsynopsisdiv>
9314 <title>Synopsis</title>
9315  <funcsynopsis><funcprototype>
9316   <funcdef>unsigned int <function>ata_scsi_flush_xlat </function></funcdef>
9317   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
9318  </funcprototype></funcsynopsis>
9319</refsynopsisdiv>
9320<refsect1>
9321 <title>Arguments</title>
9322 <variablelist>
9323  <varlistentry>
9324   <term><parameter>qc</parameter></term>
9325   <listitem>
9326    <para>
9327     Storage for translated ATA taskfile
9328    </para>
9329   </listitem>
9330  </varlistentry>
9331 </variablelist>
9332</refsect1>
9333<refsect1>
9334<title>Description</title>
9335<para>
9336   Sets up an ATA taskfile to issue FLUSH CACHE or
9337   FLUSH CACHE EXT.
9338</para>
9339</refsect1>
9340<refsect1>
9341<title>LOCKING</title>
9342<para>
9343   spin_lock_irqsave(host lock)
9344</para>
9345</refsect1>
9346<refsect1>
9347<title>RETURNS</title>
9348<para>
9349   Zero on success, non-zero on error.
9350</para>
9351</refsect1>
9352</refentry>
9353
9354<refentry id="API-scsi-6-lba-len">
9355<refentryinfo>
9356 <title>LINUX</title>
9357 <productname>Kernel Hackers Manual</productname>
9358 <date>July 2017</date>
9359</refentryinfo>
9360<refmeta>
9361 <refentrytitle><phrase>scsi_6_lba_len</phrase></refentrytitle>
9362 <manvolnum>9</manvolnum>
9363 <refmiscinfo class="version">4.1.27</refmiscinfo>
9364</refmeta>
9365<refnamediv>
9366 <refname>scsi_6_lba_len</refname>
9367 <refpurpose>
9368     Get LBA and transfer length
9369 </refpurpose>
9370</refnamediv>
9371<refsynopsisdiv>
9372 <title>Synopsis</title>
9373  <funcsynopsis><funcprototype>
9374   <funcdef>void <function>scsi_6_lba_len </function></funcdef>
9375   <paramdef>const u8 * <parameter>cdb</parameter></paramdef>
9376   <paramdef>u64 * <parameter>plba</parameter></paramdef>
9377   <paramdef>u32 * <parameter>plen</parameter></paramdef>
9378  </funcprototype></funcsynopsis>
9379</refsynopsisdiv>
9380<refsect1>
9381 <title>Arguments</title>
9382 <variablelist>
9383  <varlistentry>
9384   <term><parameter>cdb</parameter></term>
9385   <listitem>
9386    <para>
9387     SCSI command to translate
9388    </para>
9389   </listitem>
9390  </varlistentry>
9391  <varlistentry>
9392   <term><parameter>plba</parameter></term>
9393   <listitem>
9394    <para>
9395     the LBA
9396    </para>
9397   </listitem>
9398  </varlistentry>
9399  <varlistentry>
9400   <term><parameter>plen</parameter></term>
9401   <listitem>
9402    <para>
9403     the transfer length
9404    </para>
9405   </listitem>
9406  </varlistentry>
9407 </variablelist>
9408</refsect1>
9409<refsect1>
9410<title>Description</title>
9411<para>
9412   Calculate LBA and transfer length for 6-byte commands.
9413</para>
9414</refsect1>
9415</refentry>
9416
9417<refentry id="API-scsi-10-lba-len">
9418<refentryinfo>
9419 <title>LINUX</title>
9420 <productname>Kernel Hackers Manual</productname>
9421 <date>July 2017</date>
9422</refentryinfo>
9423<refmeta>
9424 <refentrytitle><phrase>scsi_10_lba_len</phrase></refentrytitle>
9425 <manvolnum>9</manvolnum>
9426 <refmiscinfo class="version">4.1.27</refmiscinfo>
9427</refmeta>
9428<refnamediv>
9429 <refname>scsi_10_lba_len</refname>
9430 <refpurpose>
9431     Get LBA and transfer length
9432 </refpurpose>
9433</refnamediv>
9434<refsynopsisdiv>
9435 <title>Synopsis</title>
9436  <funcsynopsis><funcprototype>
9437   <funcdef>void <function>scsi_10_lba_len </function></funcdef>
9438   <paramdef>const u8 * <parameter>cdb</parameter></paramdef>
9439   <paramdef>u64 * <parameter>plba</parameter></paramdef>
9440   <paramdef>u32 * <parameter>plen</parameter></paramdef>
9441  </funcprototype></funcsynopsis>
9442</refsynopsisdiv>
9443<refsect1>
9444 <title>Arguments</title>
9445 <variablelist>
9446  <varlistentry>
9447   <term><parameter>cdb</parameter></term>
9448   <listitem>
9449    <para>
9450     SCSI command to translate
9451    </para>
9452   </listitem>
9453  </varlistentry>
9454  <varlistentry>
9455   <term><parameter>plba</parameter></term>
9456   <listitem>
9457    <para>
9458     the LBA
9459    </para>
9460   </listitem>
9461  </varlistentry>
9462  <varlistentry>
9463   <term><parameter>plen</parameter></term>
9464   <listitem>
9465    <para>
9466     the transfer length
9467    </para>
9468   </listitem>
9469  </varlistentry>
9470 </variablelist>
9471</refsect1>
9472<refsect1>
9473<title>Description</title>
9474<para>
9475   Calculate LBA and transfer length for 10-byte commands.
9476</para>
9477</refsect1>
9478</refentry>
9479
9480<refentry id="API-scsi-16-lba-len">
9481<refentryinfo>
9482 <title>LINUX</title>
9483 <productname>Kernel Hackers Manual</productname>
9484 <date>July 2017</date>
9485</refentryinfo>
9486<refmeta>
9487 <refentrytitle><phrase>scsi_16_lba_len</phrase></refentrytitle>
9488 <manvolnum>9</manvolnum>
9489 <refmiscinfo class="version">4.1.27</refmiscinfo>
9490</refmeta>
9491<refnamediv>
9492 <refname>scsi_16_lba_len</refname>
9493 <refpurpose>
9494     Get LBA and transfer length
9495 </refpurpose>
9496</refnamediv>
9497<refsynopsisdiv>
9498 <title>Synopsis</title>
9499  <funcsynopsis><funcprototype>
9500   <funcdef>void <function>scsi_16_lba_len </function></funcdef>
9501   <paramdef>const u8 * <parameter>cdb</parameter></paramdef>
9502   <paramdef>u64 * <parameter>plba</parameter></paramdef>
9503   <paramdef>u32 * <parameter>plen</parameter></paramdef>
9504  </funcprototype></funcsynopsis>
9505</refsynopsisdiv>
9506<refsect1>
9507 <title>Arguments</title>
9508 <variablelist>
9509  <varlistentry>
9510   <term><parameter>cdb</parameter></term>
9511   <listitem>
9512    <para>
9513     SCSI command to translate
9514    </para>
9515   </listitem>
9516  </varlistentry>
9517  <varlistentry>
9518   <term><parameter>plba</parameter></term>
9519   <listitem>
9520    <para>
9521     the LBA
9522    </para>
9523   </listitem>
9524  </varlistentry>
9525  <varlistentry>
9526   <term><parameter>plen</parameter></term>
9527   <listitem>
9528    <para>
9529     the transfer length
9530    </para>
9531   </listitem>
9532  </varlistentry>
9533 </variablelist>
9534</refsect1>
9535<refsect1>
9536<title>Description</title>
9537<para>
9538   Calculate LBA and transfer length for 16-byte commands.
9539</para>
9540</refsect1>
9541</refentry>
9542
9543<refentry id="API-ata-scsi-verify-xlat">
9544<refentryinfo>
9545 <title>LINUX</title>
9546 <productname>Kernel Hackers Manual</productname>
9547 <date>July 2017</date>
9548</refentryinfo>
9549<refmeta>
9550 <refentrytitle><phrase>ata_scsi_verify_xlat</phrase></refentrytitle>
9551 <manvolnum>9</manvolnum>
9552 <refmiscinfo class="version">4.1.27</refmiscinfo>
9553</refmeta>
9554<refnamediv>
9555 <refname>ata_scsi_verify_xlat</refname>
9556 <refpurpose>
9557     Translate SCSI VERIFY command into an ATA one
9558 </refpurpose>
9559</refnamediv>
9560<refsynopsisdiv>
9561 <title>Synopsis</title>
9562  <funcsynopsis><funcprototype>
9563   <funcdef>unsigned int <function>ata_scsi_verify_xlat </function></funcdef>
9564   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
9565  </funcprototype></funcsynopsis>
9566</refsynopsisdiv>
9567<refsect1>
9568 <title>Arguments</title>
9569 <variablelist>
9570  <varlistentry>
9571   <term><parameter>qc</parameter></term>
9572   <listitem>
9573    <para>
9574     Storage for translated ATA taskfile
9575    </para>
9576   </listitem>
9577  </varlistentry>
9578 </variablelist>
9579</refsect1>
9580<refsect1>
9581<title>Description</title>
9582<para>
9583   Converts SCSI VERIFY command to an ATA READ VERIFY command.
9584</para>
9585</refsect1>
9586<refsect1>
9587<title>LOCKING</title>
9588<para>
9589   spin_lock_irqsave(host lock)
9590</para>
9591</refsect1>
9592<refsect1>
9593<title>RETURNS</title>
9594<para>
9595   Zero on success, non-zero on error.
9596</para>
9597</refsect1>
9598</refentry>
9599
9600<refentry id="API-ata-scsi-rw-xlat">
9601<refentryinfo>
9602 <title>LINUX</title>
9603 <productname>Kernel Hackers Manual</productname>
9604 <date>July 2017</date>
9605</refentryinfo>
9606<refmeta>
9607 <refentrytitle><phrase>ata_scsi_rw_xlat</phrase></refentrytitle>
9608 <manvolnum>9</manvolnum>
9609 <refmiscinfo class="version">4.1.27</refmiscinfo>
9610</refmeta>
9611<refnamediv>
9612 <refname>ata_scsi_rw_xlat</refname>
9613 <refpurpose>
9614     Translate SCSI r/w command into an ATA one
9615 </refpurpose>
9616</refnamediv>
9617<refsynopsisdiv>
9618 <title>Synopsis</title>
9619  <funcsynopsis><funcprototype>
9620   <funcdef>unsigned int <function>ata_scsi_rw_xlat </function></funcdef>
9621   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
9622  </funcprototype></funcsynopsis>
9623</refsynopsisdiv>
9624<refsect1>
9625 <title>Arguments</title>
9626 <variablelist>
9627  <varlistentry>
9628   <term><parameter>qc</parameter></term>
9629   <listitem>
9630    <para>
9631     Storage for translated ATA taskfile
9632    </para>
9633   </listitem>
9634  </varlistentry>
9635 </variablelist>
9636</refsect1>
9637<refsect1>
9638<title>Description</title>
9639<para>
9640   Converts any of six SCSI read/write commands into the
9641   ATA counterpart, including starting sector (LBA),
9642   sector count, and taking into account the device's LBA48
9643   support.
9644   </para><para>
9645
9646   Commands <constant>READ_6</constant>, <constant>READ_10</constant>, <constant>READ_16</constant>, <constant>WRITE_6</constant>, <constant>WRITE_10</constant>, and
9647   <constant>WRITE_16</constant> are currently supported.
9648</para>
9649</refsect1>
9650<refsect1>
9651<title>LOCKING</title>
9652<para>
9653   spin_lock_irqsave(host lock)
9654</para>
9655</refsect1>
9656<refsect1>
9657<title>RETURNS</title>
9658<para>
9659   Zero on success, non-zero on error.
9660</para>
9661</refsect1>
9662</refentry>
9663
9664<refentry id="API-ata-scsi-translate">
9665<refentryinfo>
9666 <title>LINUX</title>
9667 <productname>Kernel Hackers Manual</productname>
9668 <date>July 2017</date>
9669</refentryinfo>
9670<refmeta>
9671 <refentrytitle><phrase>ata_scsi_translate</phrase></refentrytitle>
9672 <manvolnum>9</manvolnum>
9673 <refmiscinfo class="version">4.1.27</refmiscinfo>
9674</refmeta>
9675<refnamediv>
9676 <refname>ata_scsi_translate</refname>
9677 <refpurpose>
9678     Translate then issue SCSI command to ATA device
9679 </refpurpose>
9680</refnamediv>
9681<refsynopsisdiv>
9682 <title>Synopsis</title>
9683  <funcsynopsis><funcprototype>
9684   <funcdef>int <function>ata_scsi_translate </function></funcdef>
9685   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
9686   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
9687   <paramdef>ata_xlat_func_t <parameter>xlat_func</parameter></paramdef>
9688  </funcprototype></funcsynopsis>
9689</refsynopsisdiv>
9690<refsect1>
9691 <title>Arguments</title>
9692 <variablelist>
9693  <varlistentry>
9694   <term><parameter>dev</parameter></term>
9695   <listitem>
9696    <para>
9697     ATA device to which the command is addressed
9698    </para>
9699   </listitem>
9700  </varlistentry>
9701  <varlistentry>
9702   <term><parameter>cmd</parameter></term>
9703   <listitem>
9704    <para>
9705     SCSI command to execute
9706    </para>
9707   </listitem>
9708  </varlistentry>
9709  <varlistentry>
9710   <term><parameter>xlat_func</parameter></term>
9711   <listitem>
9712    <para>
9713     Actor which translates <parameter>cmd</parameter> to an ATA taskfile
9714    </para>
9715   </listitem>
9716  </varlistentry>
9717 </variablelist>
9718</refsect1>
9719<refsect1>
9720<title>Description</title>
9721<para>
9722   Our -&gt;<function>queuecommand</function> function has decided that the SCSI
9723   command issued can be directly translated into an ATA
9724   command, rather than handled internally.
9725   </para><para>
9726
9727   This function sets up an ata_queued_cmd structure for the
9728   SCSI command, and sends that ata_queued_cmd to the hardware.
9729   </para><para>
9730
9731   The xlat_func argument (actor) returns 0 if ready to execute
9732   ATA command, else 1 to finish translation. If 1 is returned
9733   then cmd-&gt;result (and possibly cmd-&gt;sense_buffer) are assumed
9734   to be set reflecting an error condition or clean (early)
9735   termination.
9736</para>
9737</refsect1>
9738<refsect1>
9739<title>LOCKING</title>
9740<para>
9741   spin_lock_irqsave(host lock)
9742</para>
9743</refsect1>
9744<refsect1>
9745<title>RETURNS</title>
9746<para>
9747   0 on success, SCSI_ML_QUEUE_DEVICE_BUSY if the command
9748   needs to be deferred.
9749</para>
9750</refsect1>
9751</refentry>
9752
9753<refentry id="API-ata-scsi-rbuf-get">
9754<refentryinfo>
9755 <title>LINUX</title>
9756 <productname>Kernel Hackers Manual</productname>
9757 <date>July 2017</date>
9758</refentryinfo>
9759<refmeta>
9760 <refentrytitle><phrase>ata_scsi_rbuf_get</phrase></refentrytitle>
9761 <manvolnum>9</manvolnum>
9762 <refmiscinfo class="version">4.1.27</refmiscinfo>
9763</refmeta>
9764<refnamediv>
9765 <refname>ata_scsi_rbuf_get</refname>
9766 <refpurpose>
9767     Map response buffer.
9768 </refpurpose>
9769</refnamediv>
9770<refsynopsisdiv>
9771 <title>Synopsis</title>
9772  <funcsynopsis><funcprototype>
9773   <funcdef>void * <function>ata_scsi_rbuf_get </function></funcdef>
9774   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
9775   <paramdef>bool <parameter>copy_in</parameter></paramdef>
9776   <paramdef>unsigned long * <parameter>flags</parameter></paramdef>
9777  </funcprototype></funcsynopsis>
9778</refsynopsisdiv>
9779<refsect1>
9780 <title>Arguments</title>
9781 <variablelist>
9782  <varlistentry>
9783   <term><parameter>cmd</parameter></term>
9784   <listitem>
9785    <para>
9786     SCSI command containing buffer to be mapped.
9787    </para>
9788   </listitem>
9789  </varlistentry>
9790  <varlistentry>
9791   <term><parameter>copy_in</parameter></term>
9792   <listitem>
9793    <para>
9794     copy in from user buffer
9795    </para>
9796   </listitem>
9797  </varlistentry>
9798  <varlistentry>
9799   <term><parameter>flags</parameter></term>
9800   <listitem>
9801    <para>
9802     unsigned long variable to store irq enable status
9803    </para>
9804   </listitem>
9805  </varlistentry>
9806 </variablelist>
9807</refsect1>
9808<refsect1>
9809<title>Description</title>
9810<para>
9811   Prepare buffer for simulated SCSI commands.
9812</para>
9813</refsect1>
9814<refsect1>
9815<title>LOCKING</title>
9816<para>
9817   spin_lock_irqsave(ata_scsi_rbuf_lock) on success
9818</para>
9819</refsect1>
9820<refsect1>
9821<title>RETURNS</title>
9822<para>
9823   Pointer to response buffer.
9824</para>
9825</refsect1>
9826</refentry>
9827
9828<refentry id="API-ata-scsi-rbuf-put">
9829<refentryinfo>
9830 <title>LINUX</title>
9831 <productname>Kernel Hackers Manual</productname>
9832 <date>July 2017</date>
9833</refentryinfo>
9834<refmeta>
9835 <refentrytitle><phrase>ata_scsi_rbuf_put</phrase></refentrytitle>
9836 <manvolnum>9</manvolnum>
9837 <refmiscinfo class="version">4.1.27</refmiscinfo>
9838</refmeta>
9839<refnamediv>
9840 <refname>ata_scsi_rbuf_put</refname>
9841 <refpurpose>
9842     Unmap response buffer.
9843 </refpurpose>
9844</refnamediv>
9845<refsynopsisdiv>
9846 <title>Synopsis</title>
9847  <funcsynopsis><funcprototype>
9848   <funcdef>void <function>ata_scsi_rbuf_put </function></funcdef>
9849   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
9850   <paramdef>bool <parameter>copy_out</parameter></paramdef>
9851   <paramdef>unsigned long * <parameter>flags</parameter></paramdef>
9852  </funcprototype></funcsynopsis>
9853</refsynopsisdiv>
9854<refsect1>
9855 <title>Arguments</title>
9856 <variablelist>
9857  <varlistentry>
9858   <term><parameter>cmd</parameter></term>
9859   <listitem>
9860    <para>
9861     SCSI command containing buffer to be unmapped.
9862    </para>
9863   </listitem>
9864  </varlistentry>
9865  <varlistentry>
9866   <term><parameter>copy_out</parameter></term>
9867   <listitem>
9868    <para>
9869     copy out result
9870    </para>
9871   </listitem>
9872  </varlistentry>
9873  <varlistentry>
9874   <term><parameter>flags</parameter></term>
9875   <listitem>
9876    <para>
9877     <parameter>flags</parameter> passed to <function>ata_scsi_rbuf_get</function>
9878    </para>
9879   </listitem>
9880  </varlistentry>
9881 </variablelist>
9882</refsect1>
9883<refsect1>
9884<title>Description</title>
9885<para>
9886   Returns rbuf buffer.  The result is copied to <parameter>cmd</parameter>'s buffer if
9887   <parameter>copy_back</parameter> is true.
9888</para>
9889</refsect1>
9890<refsect1>
9891<title>LOCKING</title>
9892<para>
9893   Unlocks ata_scsi_rbuf_lock.
9894</para>
9895</refsect1>
9896</refentry>
9897
9898<refentry id="API-ata-scsi-rbuf-fill">
9899<refentryinfo>
9900 <title>LINUX</title>
9901 <productname>Kernel Hackers Manual</productname>
9902 <date>July 2017</date>
9903</refentryinfo>
9904<refmeta>
9905 <refentrytitle><phrase>ata_scsi_rbuf_fill</phrase></refentrytitle>
9906 <manvolnum>9</manvolnum>
9907 <refmiscinfo class="version">4.1.27</refmiscinfo>
9908</refmeta>
9909<refnamediv>
9910 <refname>ata_scsi_rbuf_fill</refname>
9911 <refpurpose>
9912     wrapper for SCSI command simulators
9913 </refpurpose>
9914</refnamediv>
9915<refsynopsisdiv>
9916 <title>Synopsis</title>
9917  <funcsynopsis><funcprototype>
9918   <funcdef>void <function>ata_scsi_rbuf_fill </function></funcdef>
9919   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
9920   <paramdef>unsigned int (*<parameter>actor</parameter>)
9921     <funcparams>struct ata_scsi_args *args, u8 *rbuf</funcparams></paramdef>
9922  </funcprototype></funcsynopsis>
9923</refsynopsisdiv>
9924<refsect1>
9925 <title>Arguments</title>
9926 <variablelist>
9927  <varlistentry>
9928   <term><parameter>args</parameter></term>
9929   <listitem>
9930    <para>
9931     device IDENTIFY data / SCSI command of interest.
9932    </para>
9933   </listitem>
9934  </varlistentry>
9935  <varlistentry>
9936   <term><parameter>actor</parameter></term>
9937   <listitem>
9938    <para>
9939     Callback hook for desired SCSI command simulator
9940    </para>
9941   </listitem>
9942  </varlistentry>
9943 </variablelist>
9944</refsect1>
9945<refsect1>
9946<title>Description</title>
9947<para>
9948   Takes care of the hard work of simulating a SCSI command...
9949   Mapping the response buffer, calling the command's handler,
9950   and handling the handler's return value.  This return value
9951   indicates whether the handler wishes the SCSI command to be
9952   completed successfully (0), or not (in which case cmd-&gt;result
9953   and sense buffer are assumed to be set).
9954</para>
9955</refsect1>
9956<refsect1>
9957<title>LOCKING</title>
9958<para>
9959   spin_lock_irqsave(host lock)
9960</para>
9961</refsect1>
9962</refentry>
9963
9964<refentry id="API-ata-scsiop-inq-std">
9965<refentryinfo>
9966 <title>LINUX</title>
9967 <productname>Kernel Hackers Manual</productname>
9968 <date>July 2017</date>
9969</refentryinfo>
9970<refmeta>
9971 <refentrytitle><phrase>ata_scsiop_inq_std</phrase></refentrytitle>
9972 <manvolnum>9</manvolnum>
9973 <refmiscinfo class="version">4.1.27</refmiscinfo>
9974</refmeta>
9975<refnamediv>
9976 <refname>ata_scsiop_inq_std</refname>
9977 <refpurpose>
9978     Simulate INQUIRY command
9979 </refpurpose>
9980</refnamediv>
9981<refsynopsisdiv>
9982 <title>Synopsis</title>
9983  <funcsynopsis><funcprototype>
9984   <funcdef>unsigned int <function>ata_scsiop_inq_std </function></funcdef>
9985   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
9986   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
9987  </funcprototype></funcsynopsis>
9988</refsynopsisdiv>
9989<refsect1>
9990 <title>Arguments</title>
9991 <variablelist>
9992  <varlistentry>
9993   <term><parameter>args</parameter></term>
9994   <listitem>
9995    <para>
9996     device IDENTIFY data / SCSI command of interest.
9997    </para>
9998   </listitem>
9999  </varlistentry>
10000  <varlistentry>
10001   <term><parameter>rbuf</parameter></term>
10002   <listitem>
10003    <para>
10004     Response buffer, to which simulated SCSI cmd output is sent.
10005    </para>
10006   </listitem>
10007  </varlistentry>
10008 </variablelist>
10009</refsect1>
10010<refsect1>
10011<title>Description</title>
10012<para>
10013   Returns standard device identification data associated
10014   with non-VPD INQUIRY command output.
10015</para>
10016</refsect1>
10017<refsect1>
10018<title>LOCKING</title>
10019<para>
10020   spin_lock_irqsave(host lock)
10021</para>
10022</refsect1>
10023</refentry>
10024
10025<refentry id="API-ata-scsiop-inq-00">
10026<refentryinfo>
10027 <title>LINUX</title>
10028 <productname>Kernel Hackers Manual</productname>
10029 <date>July 2017</date>
10030</refentryinfo>
10031<refmeta>
10032 <refentrytitle><phrase>ata_scsiop_inq_00</phrase></refentrytitle>
10033 <manvolnum>9</manvolnum>
10034 <refmiscinfo class="version">4.1.27</refmiscinfo>
10035</refmeta>
10036<refnamediv>
10037 <refname>ata_scsiop_inq_00</refname>
10038 <refpurpose>
10039     Simulate INQUIRY VPD page 0, list of pages
10040 </refpurpose>
10041</refnamediv>
10042<refsynopsisdiv>
10043 <title>Synopsis</title>
10044  <funcsynopsis><funcprototype>
10045   <funcdef>unsigned int <function>ata_scsiop_inq_00 </function></funcdef>
10046   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10047   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10048  </funcprototype></funcsynopsis>
10049</refsynopsisdiv>
10050<refsect1>
10051 <title>Arguments</title>
10052 <variablelist>
10053  <varlistentry>
10054   <term><parameter>args</parameter></term>
10055   <listitem>
10056    <para>
10057     device IDENTIFY data / SCSI command of interest.
10058    </para>
10059   </listitem>
10060  </varlistentry>
10061  <varlistentry>
10062   <term><parameter>rbuf</parameter></term>
10063   <listitem>
10064    <para>
10065     Response buffer, to which simulated SCSI cmd output is sent.
10066    </para>
10067   </listitem>
10068  </varlistentry>
10069 </variablelist>
10070</refsect1>
10071<refsect1>
10072<title>Description</title>
10073<para>
10074   Returns list of inquiry VPD pages available.
10075</para>
10076</refsect1>
10077<refsect1>
10078<title>LOCKING</title>
10079<para>
10080   spin_lock_irqsave(host lock)
10081</para>
10082</refsect1>
10083</refentry>
10084
10085<refentry id="API-ata-scsiop-inq-80">
10086<refentryinfo>
10087 <title>LINUX</title>
10088 <productname>Kernel Hackers Manual</productname>
10089 <date>July 2017</date>
10090</refentryinfo>
10091<refmeta>
10092 <refentrytitle><phrase>ata_scsiop_inq_80</phrase></refentrytitle>
10093 <manvolnum>9</manvolnum>
10094 <refmiscinfo class="version">4.1.27</refmiscinfo>
10095</refmeta>
10096<refnamediv>
10097 <refname>ata_scsiop_inq_80</refname>
10098 <refpurpose>
10099     Simulate INQUIRY VPD page 80, device serial number
10100 </refpurpose>
10101</refnamediv>
10102<refsynopsisdiv>
10103 <title>Synopsis</title>
10104  <funcsynopsis><funcprototype>
10105   <funcdef>unsigned int <function>ata_scsiop_inq_80 </function></funcdef>
10106   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10107   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10108  </funcprototype></funcsynopsis>
10109</refsynopsisdiv>
10110<refsect1>
10111 <title>Arguments</title>
10112 <variablelist>
10113  <varlistentry>
10114   <term><parameter>args</parameter></term>
10115   <listitem>
10116    <para>
10117     device IDENTIFY data / SCSI command of interest.
10118    </para>
10119   </listitem>
10120  </varlistentry>
10121  <varlistentry>
10122   <term><parameter>rbuf</parameter></term>
10123   <listitem>
10124    <para>
10125     Response buffer, to which simulated SCSI cmd output is sent.
10126    </para>
10127   </listitem>
10128  </varlistentry>
10129 </variablelist>
10130</refsect1>
10131<refsect1>
10132<title>Description</title>
10133<para>
10134   Returns ATA device serial number.
10135</para>
10136</refsect1>
10137<refsect1>
10138<title>LOCKING</title>
10139<para>
10140   spin_lock_irqsave(host lock)
10141</para>
10142</refsect1>
10143</refentry>
10144
10145<refentry id="API-ata-scsiop-inq-83">
10146<refentryinfo>
10147 <title>LINUX</title>
10148 <productname>Kernel Hackers Manual</productname>
10149 <date>July 2017</date>
10150</refentryinfo>
10151<refmeta>
10152 <refentrytitle><phrase>ata_scsiop_inq_83</phrase></refentrytitle>
10153 <manvolnum>9</manvolnum>
10154 <refmiscinfo class="version">4.1.27</refmiscinfo>
10155</refmeta>
10156<refnamediv>
10157 <refname>ata_scsiop_inq_83</refname>
10158 <refpurpose>
10159     Simulate INQUIRY VPD page 83, device identity
10160 </refpurpose>
10161</refnamediv>
10162<refsynopsisdiv>
10163 <title>Synopsis</title>
10164  <funcsynopsis><funcprototype>
10165   <funcdef>unsigned int <function>ata_scsiop_inq_83 </function></funcdef>
10166   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10167   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10168  </funcprototype></funcsynopsis>
10169</refsynopsisdiv>
10170<refsect1>
10171 <title>Arguments</title>
10172 <variablelist>
10173  <varlistentry>
10174   <term><parameter>args</parameter></term>
10175   <listitem>
10176    <para>
10177     device IDENTIFY data / SCSI command of interest.
10178    </para>
10179   </listitem>
10180  </varlistentry>
10181  <varlistentry>
10182   <term><parameter>rbuf</parameter></term>
10183   <listitem>
10184    <para>
10185     Response buffer, to which simulated SCSI cmd output is sent.
10186    </para>
10187   </listitem>
10188  </varlistentry>
10189 </variablelist>
10190</refsect1>
10191<refsect1>
10192<title>Yields two logical unit device identification designators</title>
10193<para>
10194   - vendor specific ASCII containing the ATA serial number
10195   - SAT defined <quote>t10 vendor id based</quote> containing ASCII vendor
10196   name (<quote>ATA     </quote>), model and serial numbers.
10197</para>
10198</refsect1>
10199<refsect1>
10200<title>LOCKING</title>
10201<para>
10202   spin_lock_irqsave(host lock)
10203</para>
10204</refsect1>
10205</refentry>
10206
10207<refentry id="API-ata-scsiop-inq-89">
10208<refentryinfo>
10209 <title>LINUX</title>
10210 <productname>Kernel Hackers Manual</productname>
10211 <date>July 2017</date>
10212</refentryinfo>
10213<refmeta>
10214 <refentrytitle><phrase>ata_scsiop_inq_89</phrase></refentrytitle>
10215 <manvolnum>9</manvolnum>
10216 <refmiscinfo class="version">4.1.27</refmiscinfo>
10217</refmeta>
10218<refnamediv>
10219 <refname>ata_scsiop_inq_89</refname>
10220 <refpurpose>
10221     Simulate INQUIRY VPD page 89, ATA info
10222 </refpurpose>
10223</refnamediv>
10224<refsynopsisdiv>
10225 <title>Synopsis</title>
10226  <funcsynopsis><funcprototype>
10227   <funcdef>unsigned int <function>ata_scsiop_inq_89 </function></funcdef>
10228   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10229   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10230  </funcprototype></funcsynopsis>
10231</refsynopsisdiv>
10232<refsect1>
10233 <title>Arguments</title>
10234 <variablelist>
10235  <varlistentry>
10236   <term><parameter>args</parameter></term>
10237   <listitem>
10238    <para>
10239     device IDENTIFY data / SCSI command of interest.
10240    </para>
10241   </listitem>
10242  </varlistentry>
10243  <varlistentry>
10244   <term><parameter>rbuf</parameter></term>
10245   <listitem>
10246    <para>
10247     Response buffer, to which simulated SCSI cmd output is sent.
10248    </para>
10249   </listitem>
10250  </varlistentry>
10251 </variablelist>
10252</refsect1>
10253<refsect1>
10254<title>Description</title>
10255<para>
10256   Yields SAT-specified ATA VPD page.
10257</para>
10258</refsect1>
10259<refsect1>
10260<title>LOCKING</title>
10261<para>
10262   spin_lock_irqsave(host lock)
10263</para>
10264</refsect1>
10265</refentry>
10266
10267<refentry id="API-ata-scsiop-noop">
10268<refentryinfo>
10269 <title>LINUX</title>
10270 <productname>Kernel Hackers Manual</productname>
10271 <date>July 2017</date>
10272</refentryinfo>
10273<refmeta>
10274 <refentrytitle><phrase>ata_scsiop_noop</phrase></refentrytitle>
10275 <manvolnum>9</manvolnum>
10276 <refmiscinfo class="version">4.1.27</refmiscinfo>
10277</refmeta>
10278<refnamediv>
10279 <refname>ata_scsiop_noop</refname>
10280 <refpurpose>
10281     Command handler that simply returns success.
10282 </refpurpose>
10283</refnamediv>
10284<refsynopsisdiv>
10285 <title>Synopsis</title>
10286  <funcsynopsis><funcprototype>
10287   <funcdef>unsigned int <function>ata_scsiop_noop </function></funcdef>
10288   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10289   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10290  </funcprototype></funcsynopsis>
10291</refsynopsisdiv>
10292<refsect1>
10293 <title>Arguments</title>
10294 <variablelist>
10295  <varlistentry>
10296   <term><parameter>args</parameter></term>
10297   <listitem>
10298    <para>
10299     device IDENTIFY data / SCSI command of interest.
10300    </para>
10301   </listitem>
10302  </varlistentry>
10303  <varlistentry>
10304   <term><parameter>rbuf</parameter></term>
10305   <listitem>
10306    <para>
10307     Response buffer, to which simulated SCSI cmd output is sent.
10308    </para>
10309   </listitem>
10310  </varlistentry>
10311 </variablelist>
10312</refsect1>
10313<refsect1>
10314<title>Description</title>
10315<para>
10316   No operation.  Simply returns success to caller, to indicate
10317   that the caller should successfully complete this SCSI command.
10318</para>
10319</refsect1>
10320<refsect1>
10321<title>LOCKING</title>
10322<para>
10323   spin_lock_irqsave(host lock)
10324</para>
10325</refsect1>
10326</refentry>
10327
10328<refentry id="API-modecpy">
10329<refentryinfo>
10330 <title>LINUX</title>
10331 <productname>Kernel Hackers Manual</productname>
10332 <date>July 2017</date>
10333</refentryinfo>
10334<refmeta>
10335 <refentrytitle><phrase>modecpy</phrase></refentrytitle>
10336 <manvolnum>9</manvolnum>
10337 <refmiscinfo class="version">4.1.27</refmiscinfo>
10338</refmeta>
10339<refnamediv>
10340 <refname>modecpy</refname>
10341 <refpurpose>
10342     Prepare response for MODE SENSE
10343 </refpurpose>
10344</refnamediv>
10345<refsynopsisdiv>
10346 <title>Synopsis</title>
10347  <funcsynopsis><funcprototype>
10348   <funcdef>void <function>modecpy </function></funcdef>
10349   <paramdef>u8 * <parameter>dest</parameter></paramdef>
10350   <paramdef>const u8 * <parameter>src</parameter></paramdef>
10351   <paramdef>int <parameter>n</parameter></paramdef>
10352   <paramdef>bool <parameter>changeable</parameter></paramdef>
10353  </funcprototype></funcsynopsis>
10354</refsynopsisdiv>
10355<refsect1>
10356 <title>Arguments</title>
10357 <variablelist>
10358  <varlistentry>
10359   <term><parameter>dest</parameter></term>
10360   <listitem>
10361    <para>
10362     output buffer
10363    </para>
10364   </listitem>
10365  </varlistentry>
10366  <varlistentry>
10367   <term><parameter>src</parameter></term>
10368   <listitem>
10369    <para>
10370     data being copied
10371    </para>
10372   </listitem>
10373  </varlistentry>
10374  <varlistentry>
10375   <term><parameter>n</parameter></term>
10376   <listitem>
10377    <para>
10378     length of mode page
10379    </para>
10380   </listitem>
10381  </varlistentry>
10382  <varlistentry>
10383   <term><parameter>changeable</parameter></term>
10384   <listitem>
10385    <para>
10386     whether changeable parameters are requested
10387    </para>
10388   </listitem>
10389  </varlistentry>
10390 </variablelist>
10391</refsect1>
10392<refsect1>
10393<title>Description</title>
10394<para>
10395   Generate a generic MODE SENSE page for either current or changeable
10396   parameters.
10397</para>
10398</refsect1>
10399<refsect1>
10400<title>LOCKING</title>
10401<para>
10402   None.
10403</para>
10404</refsect1>
10405</refentry>
10406
10407<refentry id="API-ata-msense-caching">
10408<refentryinfo>
10409 <title>LINUX</title>
10410 <productname>Kernel Hackers Manual</productname>
10411 <date>July 2017</date>
10412</refentryinfo>
10413<refmeta>
10414 <refentrytitle><phrase>ata_msense_caching</phrase></refentrytitle>
10415 <manvolnum>9</manvolnum>
10416 <refmiscinfo class="version">4.1.27</refmiscinfo>
10417</refmeta>
10418<refnamediv>
10419 <refname>ata_msense_caching</refname>
10420 <refpurpose>
10421     Simulate MODE SENSE caching info page
10422 </refpurpose>
10423</refnamediv>
10424<refsynopsisdiv>
10425 <title>Synopsis</title>
10426  <funcsynopsis><funcprototype>
10427   <funcdef>unsigned int <function>ata_msense_caching </function></funcdef>
10428   <paramdef>u16 * <parameter>id</parameter></paramdef>
10429   <paramdef>u8 * <parameter>buf</parameter></paramdef>
10430   <paramdef>bool <parameter>changeable</parameter></paramdef>
10431  </funcprototype></funcsynopsis>
10432</refsynopsisdiv>
10433<refsect1>
10434 <title>Arguments</title>
10435 <variablelist>
10436  <varlistentry>
10437   <term><parameter>id</parameter></term>
10438   <listitem>
10439    <para>
10440     device IDENTIFY data
10441    </para>
10442   </listitem>
10443  </varlistentry>
10444  <varlistentry>
10445   <term><parameter>buf</parameter></term>
10446   <listitem>
10447    <para>
10448     output buffer
10449    </para>
10450   </listitem>
10451  </varlistentry>
10452  <varlistentry>
10453   <term><parameter>changeable</parameter></term>
10454   <listitem>
10455    <para>
10456     whether changeable parameters are requested
10457    </para>
10458   </listitem>
10459  </varlistentry>
10460 </variablelist>
10461</refsect1>
10462<refsect1>
10463<title>Description</title>
10464<para>
10465   Generate a caching info page, which conditionally indicates
10466   write caching to the SCSI layer, depending on device
10467   capabilities.
10468</para>
10469</refsect1>
10470<refsect1>
10471<title>LOCKING</title>
10472<para>
10473   None.
10474</para>
10475</refsect1>
10476</refentry>
10477
10478<refentry id="API-ata-msense-ctl-mode">
10479<refentryinfo>
10480 <title>LINUX</title>
10481 <productname>Kernel Hackers Manual</productname>
10482 <date>July 2017</date>
10483</refentryinfo>
10484<refmeta>
10485 <refentrytitle><phrase>ata_msense_ctl_mode</phrase></refentrytitle>
10486 <manvolnum>9</manvolnum>
10487 <refmiscinfo class="version">4.1.27</refmiscinfo>
10488</refmeta>
10489<refnamediv>
10490 <refname>ata_msense_ctl_mode</refname>
10491 <refpurpose>
10492     Simulate MODE SENSE control mode page
10493 </refpurpose>
10494</refnamediv>
10495<refsynopsisdiv>
10496 <title>Synopsis</title>
10497  <funcsynopsis><funcprototype>
10498   <funcdef>unsigned int <function>ata_msense_ctl_mode </function></funcdef>
10499   <paramdef>u8 * <parameter>buf</parameter></paramdef>
10500   <paramdef>bool <parameter>changeable</parameter></paramdef>
10501  </funcprototype></funcsynopsis>
10502</refsynopsisdiv>
10503<refsect1>
10504 <title>Arguments</title>
10505 <variablelist>
10506  <varlistentry>
10507   <term><parameter>buf</parameter></term>
10508   <listitem>
10509    <para>
10510     output buffer
10511    </para>
10512   </listitem>
10513  </varlistentry>
10514  <varlistentry>
10515   <term><parameter>changeable</parameter></term>
10516   <listitem>
10517    <para>
10518     whether changeable parameters are requested
10519    </para>
10520   </listitem>
10521  </varlistentry>
10522 </variablelist>
10523</refsect1>
10524<refsect1>
10525<title>Description</title>
10526<para>
10527   Generate a generic MODE SENSE control mode page.
10528</para>
10529</refsect1>
10530<refsect1>
10531<title>LOCKING</title>
10532<para>
10533   None.
10534</para>
10535</refsect1>
10536</refentry>
10537
10538<refentry id="API-ata-msense-rw-recovery">
10539<refentryinfo>
10540 <title>LINUX</title>
10541 <productname>Kernel Hackers Manual</productname>
10542 <date>July 2017</date>
10543</refentryinfo>
10544<refmeta>
10545 <refentrytitle><phrase>ata_msense_rw_recovery</phrase></refentrytitle>
10546 <manvolnum>9</manvolnum>
10547 <refmiscinfo class="version">4.1.27</refmiscinfo>
10548</refmeta>
10549<refnamediv>
10550 <refname>ata_msense_rw_recovery</refname>
10551 <refpurpose>
10552     Simulate MODE SENSE r/w error recovery page
10553 </refpurpose>
10554</refnamediv>
10555<refsynopsisdiv>
10556 <title>Synopsis</title>
10557  <funcsynopsis><funcprototype>
10558   <funcdef>unsigned int <function>ata_msense_rw_recovery </function></funcdef>
10559   <paramdef>u8 * <parameter>buf</parameter></paramdef>
10560   <paramdef>bool <parameter>changeable</parameter></paramdef>
10561  </funcprototype></funcsynopsis>
10562</refsynopsisdiv>
10563<refsect1>
10564 <title>Arguments</title>
10565 <variablelist>
10566  <varlistentry>
10567   <term><parameter>buf</parameter></term>
10568   <listitem>
10569    <para>
10570     output buffer
10571    </para>
10572   </listitem>
10573  </varlistentry>
10574  <varlistentry>
10575   <term><parameter>changeable</parameter></term>
10576   <listitem>
10577    <para>
10578     whether changeable parameters are requested
10579    </para>
10580   </listitem>
10581  </varlistentry>
10582 </variablelist>
10583</refsect1>
10584<refsect1>
10585<title>Description</title>
10586<para>
10587   Generate a generic MODE SENSE r/w error recovery page.
10588</para>
10589</refsect1>
10590<refsect1>
10591<title>LOCKING</title>
10592<para>
10593   None.
10594</para>
10595</refsect1>
10596</refentry>
10597
10598<refentry id="API-ata-scsiop-mode-sense">
10599<refentryinfo>
10600 <title>LINUX</title>
10601 <productname>Kernel Hackers Manual</productname>
10602 <date>July 2017</date>
10603</refentryinfo>
10604<refmeta>
10605 <refentrytitle><phrase>ata_scsiop_mode_sense</phrase></refentrytitle>
10606 <manvolnum>9</manvolnum>
10607 <refmiscinfo class="version">4.1.27</refmiscinfo>
10608</refmeta>
10609<refnamediv>
10610 <refname>ata_scsiop_mode_sense</refname>
10611 <refpurpose>
10612     Simulate MODE SENSE 6, 10 commands
10613 </refpurpose>
10614</refnamediv>
10615<refsynopsisdiv>
10616 <title>Synopsis</title>
10617  <funcsynopsis><funcprototype>
10618   <funcdef>unsigned int <function>ata_scsiop_mode_sense </function></funcdef>
10619   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10620   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10621  </funcprototype></funcsynopsis>
10622</refsynopsisdiv>
10623<refsect1>
10624 <title>Arguments</title>
10625 <variablelist>
10626  <varlistentry>
10627   <term><parameter>args</parameter></term>
10628   <listitem>
10629    <para>
10630     device IDENTIFY data / SCSI command of interest.
10631    </para>
10632   </listitem>
10633  </varlistentry>
10634  <varlistentry>
10635   <term><parameter>rbuf</parameter></term>
10636   <listitem>
10637    <para>
10638     Response buffer, to which simulated SCSI cmd output is sent.
10639    </para>
10640   </listitem>
10641  </varlistentry>
10642 </variablelist>
10643</refsect1>
10644<refsect1>
10645<title>Description</title>
10646<para>
10647   Simulate MODE SENSE commands. Assume this is invoked for direct
10648   access devices (e.g. disks) only. There should be no block
10649   descriptor for other device types.
10650</para>
10651</refsect1>
10652<refsect1>
10653<title>LOCKING</title>
10654<para>
10655   spin_lock_irqsave(host lock)
10656</para>
10657</refsect1>
10658</refentry>
10659
10660<refentry id="API-ata-scsiop-read-cap">
10661<refentryinfo>
10662 <title>LINUX</title>
10663 <productname>Kernel Hackers Manual</productname>
10664 <date>July 2017</date>
10665</refentryinfo>
10666<refmeta>
10667 <refentrytitle><phrase>ata_scsiop_read_cap</phrase></refentrytitle>
10668 <manvolnum>9</manvolnum>
10669 <refmiscinfo class="version">4.1.27</refmiscinfo>
10670</refmeta>
10671<refnamediv>
10672 <refname>ata_scsiop_read_cap</refname>
10673 <refpurpose>
10674     Simulate READ CAPACITY[ 16] commands
10675 </refpurpose>
10676</refnamediv>
10677<refsynopsisdiv>
10678 <title>Synopsis</title>
10679  <funcsynopsis><funcprototype>
10680   <funcdef>unsigned int <function>ata_scsiop_read_cap </function></funcdef>
10681   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10682   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10683  </funcprototype></funcsynopsis>
10684</refsynopsisdiv>
10685<refsect1>
10686 <title>Arguments</title>
10687 <variablelist>
10688  <varlistentry>
10689   <term><parameter>args</parameter></term>
10690   <listitem>
10691    <para>
10692     device IDENTIFY data / SCSI command of interest.
10693    </para>
10694   </listitem>
10695  </varlistentry>
10696  <varlistentry>
10697   <term><parameter>rbuf</parameter></term>
10698   <listitem>
10699    <para>
10700     Response buffer, to which simulated SCSI cmd output is sent.
10701    </para>
10702   </listitem>
10703  </varlistentry>
10704 </variablelist>
10705</refsect1>
10706<refsect1>
10707<title>Description</title>
10708<para>
10709   Simulate READ CAPACITY commands.
10710</para>
10711</refsect1>
10712<refsect1>
10713<title>LOCKING</title>
10714<para>
10715   None.
10716</para>
10717</refsect1>
10718</refentry>
10719
10720<refentry id="API-ata-scsiop-report-luns">
10721<refentryinfo>
10722 <title>LINUX</title>
10723 <productname>Kernel Hackers Manual</productname>
10724 <date>July 2017</date>
10725</refentryinfo>
10726<refmeta>
10727 <refentrytitle><phrase>ata_scsiop_report_luns</phrase></refentrytitle>
10728 <manvolnum>9</manvolnum>
10729 <refmiscinfo class="version">4.1.27</refmiscinfo>
10730</refmeta>
10731<refnamediv>
10732 <refname>ata_scsiop_report_luns</refname>
10733 <refpurpose>
10734     Simulate REPORT LUNS command
10735 </refpurpose>
10736</refnamediv>
10737<refsynopsisdiv>
10738 <title>Synopsis</title>
10739  <funcsynopsis><funcprototype>
10740   <funcdef>unsigned int <function>ata_scsiop_report_luns </function></funcdef>
10741   <paramdef>struct ata_scsi_args * <parameter>args</parameter></paramdef>
10742   <paramdef>u8 * <parameter>rbuf</parameter></paramdef>
10743  </funcprototype></funcsynopsis>
10744</refsynopsisdiv>
10745<refsect1>
10746 <title>Arguments</title>
10747 <variablelist>
10748  <varlistentry>
10749   <term><parameter>args</parameter></term>
10750   <listitem>
10751    <para>
10752     device IDENTIFY data / SCSI command of interest.
10753    </para>
10754   </listitem>
10755  </varlistentry>
10756  <varlistentry>
10757   <term><parameter>rbuf</parameter></term>
10758   <listitem>
10759    <para>
10760     Response buffer, to which simulated SCSI cmd output is sent.
10761    </para>
10762   </listitem>
10763  </varlistentry>
10764 </variablelist>
10765</refsect1>
10766<refsect1>
10767<title>Description</title>
10768<para>
10769   Simulate REPORT LUNS command.
10770</para>
10771</refsect1>
10772<refsect1>
10773<title>LOCKING</title>
10774<para>
10775   spin_lock_irqsave(host lock)
10776</para>
10777</refsect1>
10778</refentry>
10779
10780<refentry id="API-atapi-xlat">
10781<refentryinfo>
10782 <title>LINUX</title>
10783 <productname>Kernel Hackers Manual</productname>
10784 <date>July 2017</date>
10785</refentryinfo>
10786<refmeta>
10787 <refentrytitle><phrase>atapi_xlat</phrase></refentrytitle>
10788 <manvolnum>9</manvolnum>
10789 <refmiscinfo class="version">4.1.27</refmiscinfo>
10790</refmeta>
10791<refnamediv>
10792 <refname>atapi_xlat</refname>
10793 <refpurpose>
10794     Initialize PACKET taskfile
10795 </refpurpose>
10796</refnamediv>
10797<refsynopsisdiv>
10798 <title>Synopsis</title>
10799  <funcsynopsis><funcprototype>
10800   <funcdef>unsigned int <function>atapi_xlat </function></funcdef>
10801   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
10802  </funcprototype></funcsynopsis>
10803</refsynopsisdiv>
10804<refsect1>
10805 <title>Arguments</title>
10806 <variablelist>
10807  <varlistentry>
10808   <term><parameter>qc</parameter></term>
10809   <listitem>
10810    <para>
10811     command structure to be initialized
10812    </para>
10813   </listitem>
10814  </varlistentry>
10815 </variablelist>
10816</refsect1>
10817<refsect1>
10818<title>LOCKING</title>
10819<para>
10820   spin_lock_irqsave(host lock)
10821</para>
10822</refsect1>
10823<refsect1>
10824<title>RETURNS</title>
10825<para>
10826   Zero on success, non-zero on failure.
10827</para>
10828</refsect1>
10829</refentry>
10830
10831<refentry id="API-ata-scsi-find-dev">
10832<refentryinfo>
10833 <title>LINUX</title>
10834 <productname>Kernel Hackers Manual</productname>
10835 <date>July 2017</date>
10836</refentryinfo>
10837<refmeta>
10838 <refentrytitle><phrase>ata_scsi_find_dev</phrase></refentrytitle>
10839 <manvolnum>9</manvolnum>
10840 <refmiscinfo class="version">4.1.27</refmiscinfo>
10841</refmeta>
10842<refnamediv>
10843 <refname>ata_scsi_find_dev</refname>
10844 <refpurpose>
10845     lookup ata_device from scsi_cmnd
10846 </refpurpose>
10847</refnamediv>
10848<refsynopsisdiv>
10849 <title>Synopsis</title>
10850  <funcsynopsis><funcprototype>
10851   <funcdef>struct ata_device * <function>ata_scsi_find_dev </function></funcdef>
10852   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
10853   <paramdef>const struct scsi_device * <parameter>scsidev</parameter></paramdef>
10854  </funcprototype></funcsynopsis>
10855</refsynopsisdiv>
10856<refsect1>
10857 <title>Arguments</title>
10858 <variablelist>
10859  <varlistentry>
10860   <term><parameter>ap</parameter></term>
10861   <listitem>
10862    <para>
10863     ATA port to which the device is attached
10864    </para>
10865   </listitem>
10866  </varlistentry>
10867  <varlistentry>
10868   <term><parameter>scsidev</parameter></term>
10869   <listitem>
10870    <para>
10871     SCSI device from which we derive the ATA device
10872    </para>
10873   </listitem>
10874  </varlistentry>
10875 </variablelist>
10876</refsect1>
10877<refsect1>
10878<title>Description</title>
10879<para>
10880   Given various information provided in struct scsi_cmnd,
10881   map that onto an ATA bus, and using that mapping
10882   determine which ata_device is associated with the
10883   SCSI command to be sent.
10884</para>
10885</refsect1>
10886<refsect1>
10887<title>LOCKING</title>
10888<para>
10889   spin_lock_irqsave(host lock)
10890</para>
10891</refsect1>
10892<refsect1>
10893<title>RETURNS</title>
10894<para>
10895   Associated ATA device, or <constant>NULL</constant> if not found.
10896</para>
10897</refsect1>
10898</refentry>
10899
10900<refentry id="API-ata-scsi-pass-thru">
10901<refentryinfo>
10902 <title>LINUX</title>
10903 <productname>Kernel Hackers Manual</productname>
10904 <date>July 2017</date>
10905</refentryinfo>
10906<refmeta>
10907 <refentrytitle><phrase>ata_scsi_pass_thru</phrase></refentrytitle>
10908 <manvolnum>9</manvolnum>
10909 <refmiscinfo class="version">4.1.27</refmiscinfo>
10910</refmeta>
10911<refnamediv>
10912 <refname>ata_scsi_pass_thru</refname>
10913 <refpurpose>
10914     convert ATA pass-thru CDB to taskfile
10915 </refpurpose>
10916</refnamediv>
10917<refsynopsisdiv>
10918 <title>Synopsis</title>
10919  <funcsynopsis><funcprototype>
10920   <funcdef>unsigned int <function>ata_scsi_pass_thru </function></funcdef>
10921   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
10922  </funcprototype></funcsynopsis>
10923</refsynopsisdiv>
10924<refsect1>
10925 <title>Arguments</title>
10926 <variablelist>
10927  <varlistentry>
10928   <term><parameter>qc</parameter></term>
10929   <listitem>
10930    <para>
10931     command structure to be initialized
10932    </para>
10933   </listitem>
10934  </varlistentry>
10935 </variablelist>
10936</refsect1>
10937<refsect1>
10938<title>Description</title>
10939<para>
10940   Handles either 12 or 16-byte versions of the CDB.
10941</para>
10942</refsect1>
10943<refsect1>
10944<title>RETURNS</title>
10945<para>
10946   Zero on success, non-zero on failure.
10947</para>
10948</refsect1>
10949</refentry>
10950
10951<refentry id="API-ata-mselect-caching">
10952<refentryinfo>
10953 <title>LINUX</title>
10954 <productname>Kernel Hackers Manual</productname>
10955 <date>July 2017</date>
10956</refentryinfo>
10957<refmeta>
10958 <refentrytitle><phrase>ata_mselect_caching</phrase></refentrytitle>
10959 <manvolnum>9</manvolnum>
10960 <refmiscinfo class="version">4.1.27</refmiscinfo>
10961</refmeta>
10962<refnamediv>
10963 <refname>ata_mselect_caching</refname>
10964 <refpurpose>
10965     Simulate MODE SELECT for caching info page
10966 </refpurpose>
10967</refnamediv>
10968<refsynopsisdiv>
10969 <title>Synopsis</title>
10970  <funcsynopsis><funcprototype>
10971   <funcdef>int <function>ata_mselect_caching </function></funcdef>
10972   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
10973   <paramdef>const u8 * <parameter>buf</parameter></paramdef>
10974   <paramdef>int <parameter>len</parameter></paramdef>
10975  </funcprototype></funcsynopsis>
10976</refsynopsisdiv>
10977<refsect1>
10978 <title>Arguments</title>
10979 <variablelist>
10980  <varlistentry>
10981   <term><parameter>qc</parameter></term>
10982   <listitem>
10983    <para>
10984     Storage for translated ATA taskfile
10985    </para>
10986   </listitem>
10987  </varlistentry>
10988  <varlistentry>
10989   <term><parameter>buf</parameter></term>
10990   <listitem>
10991    <para>
10992     input buffer
10993    </para>
10994   </listitem>
10995  </varlistentry>
10996  <varlistentry>
10997   <term><parameter>len</parameter></term>
10998   <listitem>
10999    <para>
11000     number of valid bytes in the input buffer
11001    </para>
11002   </listitem>
11003  </varlistentry>
11004 </variablelist>
11005</refsect1>
11006<refsect1>
11007<title>Description</title>
11008<para>
11009   Prepare a taskfile to modify caching information for the device.
11010</para>
11011</refsect1>
11012<refsect1>
11013<title>LOCKING</title>
11014<para>
11015   None.
11016</para>
11017</refsect1>
11018</refentry>
11019
11020<refentry id="API-ata-scsi-mode-select-xlat">
11021<refentryinfo>
11022 <title>LINUX</title>
11023 <productname>Kernel Hackers Manual</productname>
11024 <date>July 2017</date>
11025</refentryinfo>
11026<refmeta>
11027 <refentrytitle><phrase>ata_scsi_mode_select_xlat</phrase></refentrytitle>
11028 <manvolnum>9</manvolnum>
11029 <refmiscinfo class="version">4.1.27</refmiscinfo>
11030</refmeta>
11031<refnamediv>
11032 <refname>ata_scsi_mode_select_xlat</refname>
11033 <refpurpose>
11034     Simulate MODE SELECT 6, 10 commands
11035 </refpurpose>
11036</refnamediv>
11037<refsynopsisdiv>
11038 <title>Synopsis</title>
11039  <funcsynopsis><funcprototype>
11040   <funcdef>unsigned int <function>ata_scsi_mode_select_xlat </function></funcdef>
11041   <paramdef>struct ata_queued_cmd * <parameter>qc</parameter></paramdef>
11042  </funcprototype></funcsynopsis>
11043</refsynopsisdiv>
11044<refsect1>
11045 <title>Arguments</title>
11046 <variablelist>
11047  <varlistentry>
11048   <term><parameter>qc</parameter></term>
11049   <listitem>
11050    <para>
11051     Storage for translated ATA taskfile
11052    </para>
11053   </listitem>
11054  </varlistentry>
11055 </variablelist>
11056</refsect1>
11057<refsect1>
11058<title>Description</title>
11059<para>
11060   Converts a MODE SELECT command to an ATA SET FEATURES taskfile.
11061   Assume this is invoked for direct access devices (e.g. disks) only.
11062   There should be no block descriptor for other device types.
11063</para>
11064</refsect1>
11065<refsect1>
11066<title>LOCKING</title>
11067<para>
11068   spin_lock_irqsave(host lock)
11069</para>
11070</refsect1>
11071</refentry>
11072
11073<refentry id="API-ata-get-xlat-func">
11074<refentryinfo>
11075 <title>LINUX</title>
11076 <productname>Kernel Hackers Manual</productname>
11077 <date>July 2017</date>
11078</refentryinfo>
11079<refmeta>
11080 <refentrytitle><phrase>ata_get_xlat_func</phrase></refentrytitle>
11081 <manvolnum>9</manvolnum>
11082 <refmiscinfo class="version">4.1.27</refmiscinfo>
11083</refmeta>
11084<refnamediv>
11085 <refname>ata_get_xlat_func</refname>
11086 <refpurpose>
11087     check if SCSI to ATA translation is possible
11088 </refpurpose>
11089</refnamediv>
11090<refsynopsisdiv>
11091 <title>Synopsis</title>
11092  <funcsynopsis><funcprototype>
11093   <funcdef>ata_xlat_func_t <function>ata_get_xlat_func </function></funcdef>
11094   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
11095   <paramdef>u8 <parameter>cmd</parameter></paramdef>
11096  </funcprototype></funcsynopsis>
11097</refsynopsisdiv>
11098<refsect1>
11099 <title>Arguments</title>
11100 <variablelist>
11101  <varlistentry>
11102   <term><parameter>dev</parameter></term>
11103   <listitem>
11104    <para>
11105     ATA device
11106    </para>
11107   </listitem>
11108  </varlistentry>
11109  <varlistentry>
11110   <term><parameter>cmd</parameter></term>
11111   <listitem>
11112    <para>
11113     SCSI command opcode to consider
11114    </para>
11115   </listitem>
11116  </varlistentry>
11117 </variablelist>
11118</refsect1>
11119<refsect1>
11120<title>Description</title>
11121<para>
11122   Look up the SCSI command given, and determine whether the
11123   SCSI command is to be translated or simulated.
11124</para>
11125</refsect1>
11126<refsect1>
11127<title>RETURNS</title>
11128<para>
11129   Pointer to translation function if possible, <constant>NULL</constant> if not.
11130</para>
11131</refsect1>
11132</refentry>
11133
11134<refentry id="API-ata-scsi-dump-cdb">
11135<refentryinfo>
11136 <title>LINUX</title>
11137 <productname>Kernel Hackers Manual</productname>
11138 <date>July 2017</date>
11139</refentryinfo>
11140<refmeta>
11141 <refentrytitle><phrase>ata_scsi_dump_cdb</phrase></refentrytitle>
11142 <manvolnum>9</manvolnum>
11143 <refmiscinfo class="version">4.1.27</refmiscinfo>
11144</refmeta>
11145<refnamediv>
11146 <refname>ata_scsi_dump_cdb</refname>
11147 <refpurpose>
11148     dump SCSI command contents to dmesg
11149 </refpurpose>
11150</refnamediv>
11151<refsynopsisdiv>
11152 <title>Synopsis</title>
11153  <funcsynopsis><funcprototype>
11154   <funcdef>void <function>ata_scsi_dump_cdb </function></funcdef>
11155   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
11156   <paramdef>struct scsi_cmnd * <parameter>cmd</parameter></paramdef>
11157  </funcprototype></funcsynopsis>
11158</refsynopsisdiv>
11159<refsect1>
11160 <title>Arguments</title>
11161 <variablelist>
11162  <varlistentry>
11163   <term><parameter>ap</parameter></term>
11164   <listitem>
11165    <para>
11166     ATA port to which the command was being sent
11167    </para>
11168   </listitem>
11169  </varlistentry>
11170  <varlistentry>
11171   <term><parameter>cmd</parameter></term>
11172   <listitem>
11173    <para>
11174     SCSI command to dump
11175    </para>
11176   </listitem>
11177  </varlistentry>
11178 </variablelist>
11179</refsect1>
11180<refsect1>
11181<title>Description</title>
11182<para>
11183   Prints the contents of a SCSI command via <function>printk</function>.
11184</para>
11185</refsect1>
11186</refentry>
11187
11188<refentry id="API-ata-scsi-offline-dev">
11189<refentryinfo>
11190 <title>LINUX</title>
11191 <productname>Kernel Hackers Manual</productname>
11192 <date>July 2017</date>
11193</refentryinfo>
11194<refmeta>
11195 <refentrytitle><phrase>ata_scsi_offline_dev</phrase></refentrytitle>
11196 <manvolnum>9</manvolnum>
11197 <refmiscinfo class="version">4.1.27</refmiscinfo>
11198</refmeta>
11199<refnamediv>
11200 <refname>ata_scsi_offline_dev</refname>
11201 <refpurpose>
11202     offline attached SCSI device
11203 </refpurpose>
11204</refnamediv>
11205<refsynopsisdiv>
11206 <title>Synopsis</title>
11207  <funcsynopsis><funcprototype>
11208   <funcdef>int <function>ata_scsi_offline_dev </function></funcdef>
11209   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
11210  </funcprototype></funcsynopsis>
11211</refsynopsisdiv>
11212<refsect1>
11213 <title>Arguments</title>
11214 <variablelist>
11215  <varlistentry>
11216   <term><parameter>dev</parameter></term>
11217   <listitem>
11218    <para>
11219     ATA device to offline attached SCSI device for
11220    </para>
11221   </listitem>
11222  </varlistentry>
11223 </variablelist>
11224</refsect1>
11225<refsect1>
11226<title>Description</title>
11227<para>
11228   This function is called from <function>ata_eh_hotplug</function> and responsible
11229   for taking the SCSI device attached to <parameter>dev</parameter> offline.  This
11230   function is called with host lock which protects dev-&gt;sdev
11231   against clearing.
11232</para>
11233</refsect1>
11234<refsect1>
11235<title>LOCKING</title>
11236<para>
11237   spin_lock_irqsave(host lock)
11238</para>
11239</refsect1>
11240<refsect1>
11241<title>RETURNS</title>
11242<para>
11243   1 if attached SCSI device exists, 0 otherwise.
11244</para>
11245</refsect1>
11246</refentry>
11247
11248<refentry id="API-ata-scsi-remove-dev">
11249<refentryinfo>
11250 <title>LINUX</title>
11251 <productname>Kernel Hackers Manual</productname>
11252 <date>July 2017</date>
11253</refentryinfo>
11254<refmeta>
11255 <refentrytitle><phrase>ata_scsi_remove_dev</phrase></refentrytitle>
11256 <manvolnum>9</manvolnum>
11257 <refmiscinfo class="version">4.1.27</refmiscinfo>
11258</refmeta>
11259<refnamediv>
11260 <refname>ata_scsi_remove_dev</refname>
11261 <refpurpose>
11262     remove attached SCSI device
11263 </refpurpose>
11264</refnamediv>
11265<refsynopsisdiv>
11266 <title>Synopsis</title>
11267  <funcsynopsis><funcprototype>
11268   <funcdef>void <function>ata_scsi_remove_dev </function></funcdef>
11269   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
11270  </funcprototype></funcsynopsis>
11271</refsynopsisdiv>
11272<refsect1>
11273 <title>Arguments</title>
11274 <variablelist>
11275  <varlistentry>
11276   <term><parameter>dev</parameter></term>
11277   <listitem>
11278    <para>
11279     ATA device to remove attached SCSI device for
11280    </para>
11281   </listitem>
11282  </varlistentry>
11283 </variablelist>
11284</refsect1>
11285<refsect1>
11286<title>Description</title>
11287<para>
11288   This function is called from <function>ata_eh_scsi_hotplug</function> and
11289   responsible for removing the SCSI device attached to <parameter>dev</parameter>.
11290</para>
11291</refsect1>
11292<refsect1>
11293<title>LOCKING</title>
11294<para>
11295   Kernel thread context (may sleep).
11296</para>
11297</refsect1>
11298</refentry>
11299
11300<refentry id="API-ata-scsi-media-change-notify">
11301<refentryinfo>
11302 <title>LINUX</title>
11303 <productname>Kernel Hackers Manual</productname>
11304 <date>July 2017</date>
11305</refentryinfo>
11306<refmeta>
11307 <refentrytitle><phrase>ata_scsi_media_change_notify</phrase></refentrytitle>
11308 <manvolnum>9</manvolnum>
11309 <refmiscinfo class="version">4.1.27</refmiscinfo>
11310</refmeta>
11311<refnamediv>
11312 <refname>ata_scsi_media_change_notify</refname>
11313 <refpurpose>
11314     send media change event
11315 </refpurpose>
11316</refnamediv>
11317<refsynopsisdiv>
11318 <title>Synopsis</title>
11319  <funcsynopsis><funcprototype>
11320   <funcdef>void <function>ata_scsi_media_change_notify </function></funcdef>
11321   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
11322  </funcprototype></funcsynopsis>
11323</refsynopsisdiv>
11324<refsect1>
11325 <title>Arguments</title>
11326 <variablelist>
11327  <varlistentry>
11328   <term><parameter>dev</parameter></term>
11329   <listitem>
11330    <para>
11331     Pointer to the disk device with media change event
11332    </para>
11333   </listitem>
11334  </varlistentry>
11335 </variablelist>
11336</refsect1>
11337<refsect1>
11338<title>Description</title>
11339<para>
11340   Tell the block layer to send a media change notification
11341   event.
11342</para>
11343</refsect1>
11344<refsect1>
11345<title>LOCKING</title>
11346<para>
11347   spin_lock_irqsave(host lock)
11348</para>
11349</refsect1>
11350</refentry>
11351
11352<refentry id="API-ata-scsi-hotplug">
11353<refentryinfo>
11354 <title>LINUX</title>
11355 <productname>Kernel Hackers Manual</productname>
11356 <date>July 2017</date>
11357</refentryinfo>
11358<refmeta>
11359 <refentrytitle><phrase>ata_scsi_hotplug</phrase></refentrytitle>
11360 <manvolnum>9</manvolnum>
11361 <refmiscinfo class="version">4.1.27</refmiscinfo>
11362</refmeta>
11363<refnamediv>
11364 <refname>ata_scsi_hotplug</refname>
11365 <refpurpose>
11366     SCSI part of hotplug
11367 </refpurpose>
11368</refnamediv>
11369<refsynopsisdiv>
11370 <title>Synopsis</title>
11371  <funcsynopsis><funcprototype>
11372   <funcdef>void <function>ata_scsi_hotplug </function></funcdef>
11373   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
11374  </funcprototype></funcsynopsis>
11375</refsynopsisdiv>
11376<refsect1>
11377 <title>Arguments</title>
11378 <variablelist>
11379  <varlistentry>
11380   <term><parameter>work</parameter></term>
11381   <listitem>
11382    <para>
11383     Pointer to ATA port to perform SCSI hotplug on
11384    </para>
11385   </listitem>
11386  </varlistentry>
11387 </variablelist>
11388</refsect1>
11389<refsect1>
11390<title>Description</title>
11391<para>
11392   Perform SCSI part of hotplug.  It's executed from a separate
11393   workqueue after EH completes.  This is necessary because SCSI
11394   hot plugging requires working EH and hot unplugging is
11395   synchronized with hot plugging with a mutex.
11396</para>
11397</refsect1>
11398<refsect1>
11399<title>LOCKING</title>
11400<para>
11401   Kernel thread context (may sleep).
11402</para>
11403</refsect1>
11404</refentry>
11405
11406<refentry id="API-ata-scsi-user-scan">
11407<refentryinfo>
11408 <title>LINUX</title>
11409 <productname>Kernel Hackers Manual</productname>
11410 <date>July 2017</date>
11411</refentryinfo>
11412<refmeta>
11413 <refentrytitle><phrase>ata_scsi_user_scan</phrase></refentrytitle>
11414 <manvolnum>9</manvolnum>
11415 <refmiscinfo class="version">4.1.27</refmiscinfo>
11416</refmeta>
11417<refnamediv>
11418 <refname>ata_scsi_user_scan</refname>
11419 <refpurpose>
11420     indication for user-initiated bus scan
11421 </refpurpose>
11422</refnamediv>
11423<refsynopsisdiv>
11424 <title>Synopsis</title>
11425  <funcsynopsis><funcprototype>
11426   <funcdef>int <function>ata_scsi_user_scan </function></funcdef>
11427   <paramdef>struct Scsi_Host * <parameter>shost</parameter></paramdef>
11428   <paramdef>unsigned int <parameter>channel</parameter></paramdef>
11429   <paramdef>unsigned int <parameter>id</parameter></paramdef>
11430   <paramdef>u64 <parameter>lun</parameter></paramdef>
11431  </funcprototype></funcsynopsis>
11432</refsynopsisdiv>
11433<refsect1>
11434 <title>Arguments</title>
11435 <variablelist>
11436  <varlistentry>
11437   <term><parameter>shost</parameter></term>
11438   <listitem>
11439    <para>
11440     SCSI host to scan
11441    </para>
11442   </listitem>
11443  </varlistentry>
11444  <varlistentry>
11445   <term><parameter>channel</parameter></term>
11446   <listitem>
11447    <para>
11448     Channel to scan
11449    </para>
11450   </listitem>
11451  </varlistentry>
11452  <varlistentry>
11453   <term><parameter>id</parameter></term>
11454   <listitem>
11455    <para>
11456     ID to scan
11457    </para>
11458   </listitem>
11459  </varlistentry>
11460  <varlistentry>
11461   <term><parameter>lun</parameter></term>
11462   <listitem>
11463    <para>
11464     LUN to scan
11465    </para>
11466   </listitem>
11467  </varlistentry>
11468 </variablelist>
11469</refsect1>
11470<refsect1>
11471<title>Description</title>
11472<para>
11473   This function is called when user explicitly requests bus
11474   scan.  Set probe pending flag and invoke EH.
11475</para>
11476</refsect1>
11477<refsect1>
11478<title>LOCKING</title>
11479<para>
11480   SCSI layer (we don't care)
11481</para>
11482</refsect1>
11483<refsect1>
11484<title>RETURNS</title>
11485<para>
11486   Zero.
11487</para>
11488</refsect1>
11489</refentry>
11490
11491<refentry id="API-ata-scsi-dev-rescan">
11492<refentryinfo>
11493 <title>LINUX</title>
11494 <productname>Kernel Hackers Manual</productname>
11495 <date>July 2017</date>
11496</refentryinfo>
11497<refmeta>
11498 <refentrytitle><phrase>ata_scsi_dev_rescan</phrase></refentrytitle>
11499 <manvolnum>9</manvolnum>
11500 <refmiscinfo class="version">4.1.27</refmiscinfo>
11501</refmeta>
11502<refnamediv>
11503 <refname>ata_scsi_dev_rescan</refname>
11504 <refpurpose>
11505     initiate <function>scsi_rescan_device</function>
11506 </refpurpose>
11507</refnamediv>
11508<refsynopsisdiv>
11509 <title>Synopsis</title>
11510  <funcsynopsis><funcprototype>
11511   <funcdef>void <function>ata_scsi_dev_rescan </function></funcdef>
11512   <paramdef>struct work_struct * <parameter>work</parameter></paramdef>
11513  </funcprototype></funcsynopsis>
11514</refsynopsisdiv>
11515<refsect1>
11516 <title>Arguments</title>
11517 <variablelist>
11518  <varlistentry>
11519   <term><parameter>work</parameter></term>
11520   <listitem>
11521    <para>
11522     Pointer to ATA port to perform <function>scsi_rescan_device</function>
11523    </para>
11524   </listitem>
11525  </varlistentry>
11526 </variablelist>
11527</refsect1>
11528<refsect1>
11529<title>Description</title>
11530<para>
11531   After ATA pass thru (SAT) commands are executed successfully,
11532   libata need to propagate the changes to SCSI layer.
11533</para>
11534</refsect1>
11535<refsect1>
11536<title>LOCKING</title>
11537<para>
11538   Kernel thread context (may sleep).
11539</para>
11540</refsect1>
11541</refentry>
11542
11543  </chapter>
11544
11545  <chapter id="ataExceptions">
11546     <title>ATA errors and exceptions</title>
11547
11548  <para>
11549  This chapter tries to identify what error/exception conditions exist
11550  for ATA/ATAPI devices and describe how they should be handled in
11551  implementation-neutral way.
11552  </para>
11553
11554  <para>
11555  The term 'error' is used to describe conditions where either an
11556  explicit error condition is reported from device or a command has
11557  timed out.
11558  </para>
11559
11560  <para>
11561  The term 'exception' is either used to describe exceptional
11562  conditions which are not errors (say, power or hotplug events), or
11563  to describe both errors and non-error exceptional conditions.  Where
11564  explicit distinction between error and exception is necessary, the
11565  term 'non-error exception' is used.
11566  </para>
11567
11568  <sect1 id="excat">
11569     <title>Exception categories</title>
11570     <para>
11571     Exceptions are described primarily with respect to legacy
11572     taskfile + bus master IDE interface.  If a controller provides
11573     other better mechanism for error reporting, mapping those into
11574     categories described below shouldn't be difficult.
11575     </para>
11576
11577     <para>
11578     In the following sections, two recovery actions - reset and
11579     reconfiguring transport - are mentioned.  These are described
11580     further in <xref linkend="exrec"/>.
11581     </para>
11582
11583     <sect2 id="excatHSMviolation">
11584        <title>HSM violation</title>
11585        <para>
11586        This error is indicated when STATUS value doesn't match HSM
11587        requirement during issuing or execution any ATA/ATAPI command.
11588        </para>
11589
11590	<itemizedlist>
11591	<title>Examples</title>
11592
11593        <listitem>
11594	<para>
11595	ATA_STATUS doesn't contain !BSY &amp;&amp; DRDY &amp;&amp; !DRQ while trying
11596	to issue a command.
11597        </para>
11598	</listitem>
11599
11600        <listitem>
11601	<para>
11602	!BSY &amp;&amp; !DRQ during PIO data transfer.
11603        </para>
11604	</listitem>
11605
11606        <listitem>
11607	<para>
11608	DRQ on command completion.
11609        </para>
11610	</listitem>
11611
11612        <listitem>
11613	<para>
11614	!BSY &amp;&amp; ERR after CDB transfer starts but before the
11615        last byte of CDB is transferred.  ATA/ATAPI standard states
11616        that &quot;The device shall not terminate the PACKET command
11617        with an error before the last byte of the command packet has
11618        been written&quot; in the error outputs description of PACKET
11619        command and the state diagram doesn't include such
11620        transitions.
11621	</para>
11622	</listitem>
11623
11624	</itemizedlist>
11625
11626	<para>
11627	In these cases, HSM is violated and not much information
11628	regarding the error can be acquired from STATUS or ERROR
11629	register.  IOW, this error can be anything - driver bug,
11630	faulty device, controller and/or cable.
11631	</para>
11632
11633	<para>
11634	As HSM is violated, reset is necessary to restore known state.
11635	Reconfiguring transport for lower speed might be helpful too
11636	as transmission errors sometimes cause this kind of errors.
11637	</para>
11638     </sect2>
11639     
11640     <sect2 id="excatDevErr">
11641        <title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title>
11642
11643	<para>
11644	These are errors detected and reported by ATA/ATAPI devices
11645	indicating device problems.  For this type of errors, STATUS
11646	and ERROR register values are valid and describe error
11647	condition.  Note that some of ATA bus errors are detected by
11648	ATA/ATAPI devices and reported using the same mechanism as
11649	device errors.  Those cases are described later in this
11650	section.
11651	</para>
11652
11653	<para>
11654	For ATA commands, this type of errors are indicated by !BSY
11655	&amp;&amp; ERR during command execution and on completion.
11656	</para>
11657
11658	<para>For ATAPI commands,</para>
11659
11660	<itemizedlist>
11661
11662	<listitem>
11663	<para>
11664	!BSY &amp;&amp; ERR &amp;&amp; ABRT right after issuing PACKET
11665	indicates that PACKET command is not supported and falls in
11666	this category.
11667	</para>
11668	</listitem>
11669
11670	<listitem>
11671	<para>
11672	!BSY &amp;&amp; ERR(==CHK) &amp;&amp; !ABRT after the last
11673	byte of CDB is transferred indicates CHECK CONDITION and
11674	doesn't fall in this category.
11675	</para>
11676	</listitem>
11677
11678	<listitem>
11679	<para>
11680	!BSY &amp;&amp; ERR(==CHK) &amp;&amp; ABRT after the last byte
11681        of CDB is transferred *probably* indicates CHECK CONDITION and
11682        doesn't fall in this category.
11683	</para>
11684	</listitem>
11685
11686	</itemizedlist>
11687
11688	<para>
11689	Of errors detected as above, the followings are not ATA/ATAPI
11690	device errors but ATA bus errors and should be handled
11691	according to <xref linkend="excatATAbusErr"/>.
11692	</para>
11693
11694	<variablelist>
11695
11696	   <varlistentry>
11697	   <term>CRC error during data transfer</term>
11698	   <listitem>
11699	   <para>
11700	   This is indicated by ICRC bit in the ERROR register and
11701	   means that corruption occurred during data transfer.  Up to
11702	   ATA/ATAPI-7, the standard specifies that this bit is only
11703	   applicable to UDMA transfers but ATA/ATAPI-8 draft revision
11704	   1f says that the bit may be applicable to multiword DMA and
11705	   PIO.
11706	   </para>
11707	   </listitem>
11708	   </varlistentry>
11709
11710	   <varlistentry>
11711	   <term>ABRT error during data transfer or on completion</term>
11712	   <listitem>
11713	   <para>
11714	   Up to ATA/ATAPI-7, the standard specifies that ABRT could be
11715	   set on ICRC errors and on cases where a device is not able
11716	   to complete a command.  Combined with the fact that MWDMA
11717	   and PIO transfer errors aren't allowed to use ICRC bit up to
11718	   ATA/ATAPI-7, it seems to imply that ABRT bit alone could
11719	   indicate transfer errors.
11720	   </para>
11721	   <para>
11722	   However, ATA/ATAPI-8 draft revision 1f removes the part
11723	   that ICRC errors can turn on ABRT.  So, this is kind of
11724	   gray area.  Some heuristics are needed here.
11725	   </para>
11726	   </listitem>
11727	   </varlistentry>
11728
11729	</variablelist>
11730
11731	<para>
11732	ATA/ATAPI device errors can be further categorized as follows.
11733	</para>
11734
11735	<variablelist>
11736
11737	   <varlistentry>
11738	   <term>Media errors</term>
11739	   <listitem>
11740	   <para>
11741	   This is indicated by UNC bit in the ERROR register.  ATA
11742	   devices reports UNC error only after certain number of
11743	   retries cannot recover the data, so there's nothing much
11744	   else to do other than notifying upper layer.
11745	   </para>
11746	   <para>
11747	   READ and WRITE commands report CHS or LBA of the first
11748	   failed sector but ATA/ATAPI standard specifies that the
11749	   amount of transferred data on error completion is
11750	   indeterminate, so we cannot assume that sectors preceding
11751	   the failed sector have been transferred and thus cannot
11752	   complete those sectors successfully as SCSI does.
11753	   </para>
11754	   </listitem>
11755	   </varlistentry>
11756
11757	   <varlistentry>
11758	   <term>Media changed / media change requested error</term>
11759	   <listitem>
11760	   <para>
11761	   &lt;&lt;TODO: fill here&gt;&gt;
11762	   </para>
11763	   </listitem>
11764	   </varlistentry>
11765
11766	   <varlistentry><term>Address error</term>
11767	   <listitem>
11768	   <para>
11769	   This is indicated by IDNF bit in the ERROR register.
11770	   Report to upper layer.
11771	   </para>
11772	   </listitem>
11773	   </varlistentry>
11774
11775	   <varlistentry><term>Other errors</term>
11776	   <listitem>
11777	   <para>
11778	   This can be invalid command or parameter indicated by ABRT
11779	   ERROR bit or some other error condition.  Note that ABRT
11780	   bit can indicate a lot of things including ICRC and Address
11781	   errors.  Heuristics needed.
11782	   </para>
11783	   </listitem>
11784	   </varlistentry>
11785
11786	</variablelist>
11787
11788	<para>
11789	Depending on commands, not all STATUS/ERROR bits are
11790	applicable.  These non-applicable bits are marked with
11791	&quot;na&quot; in the output descriptions but up to ATA/ATAPI-7
11792	no definition of &quot;na&quot; can be found.  However,
11793	ATA/ATAPI-8 draft revision 1f describes &quot;N/A&quot; as
11794	follows.
11795	</para>
11796
11797	<blockquote>
11798	<variablelist>
11799	   <varlistentry><term>3.2.3.3a N/A</term>
11800	   <listitem>
11801	   <para>
11802	   A keyword the indicates a field has no defined value in
11803	   this standard and should not be checked by the host or
11804	   device. N/A fields should be cleared to zero.
11805	   </para>
11806	   </listitem>
11807	   </varlistentry>
11808	</variablelist>
11809	</blockquote>
11810
11811	<para>
11812	So, it seems reasonable to assume that &quot;na&quot; bits are
11813	cleared to zero by devices and thus need no explicit masking.
11814	</para>
11815
11816     </sect2>
11817
11818     <sect2 id="excatATAPIcc">
11819        <title>ATAPI device CHECK CONDITION</title>
11820
11821	<para>
11822	ATAPI device CHECK CONDITION error is indicated by set CHK bit
11823	(ERR bit) in the STATUS register after the last byte of CDB is
11824	transferred for a PACKET command.  For this kind of errors,
11825	sense data should be acquired to gather information regarding
11826	the errors.  REQUEST SENSE packet command should be used to
11827	acquire sense data.
11828	</para>
11829
11830	<para>
11831	Once sense data is acquired, this type of errors can be
11832	handled similarly to other SCSI errors.  Note that sense data
11833	may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR
11834	&amp;&amp; ASC/ASCQ 47h/00h SCSI PARITY ERROR).  In such
11835	cases, the error should be considered as an ATA bus error and
11836	handled according to <xref linkend="excatATAbusErr"/>.
11837	</para>
11838
11839     </sect2>
11840
11841     <sect2 id="excatNCQerr">
11842        <title>ATA device error (NCQ)</title>
11843
11844	<para>
11845	NCQ command error is indicated by cleared BSY and set ERR bit
11846	during NCQ command phase (one or more NCQ commands
11847	outstanding).  Although STATUS and ERROR registers will
11848	contain valid values describing the error, READ LOG EXT is
11849	required to clear the error condition, determine which command
11850	has failed and acquire more information.
11851	</para>
11852
11853	<para>
11854	READ LOG EXT Log Page 10h reports which tag has failed and
11855	taskfile register values describing the error.  With this
11856	information the failed command can be handled as a normal ATA
11857	command error as in <xref linkend="excatDevErr"/> and all
11858	other in-flight commands must be retried.  Note that this
11859	retry should not be counted - it's likely that commands
11860	retried this way would have completed normally if it were not
11861	for the failed command.
11862	</para>
11863
11864	<para>
11865	Note that ATA bus errors can be reported as ATA device NCQ
11866	errors.  This should be handled as described in <xref
11867	linkend="excatATAbusErr"/>.
11868	</para>
11869
11870	<para>
11871	If READ LOG EXT Log Page 10h fails or reports NQ, we're
11872	thoroughly screwed.  This condition should be treated
11873	according to <xref linkend="excatHSMviolation"/>.
11874	</para>
11875
11876     </sect2>
11877
11878     <sect2 id="excatATAbusErr">
11879        <title>ATA bus error</title>
11880
11881	<para>
11882	ATA bus error means that data corruption occurred during
11883	transmission over ATA bus (SATA or PATA).  This type of errors
11884	can be indicated by
11885	</para>
11886
11887	<itemizedlist>
11888
11889	<listitem>
11890	<para>
11891	ICRC or ABRT error as described in <xref linkend="excatDevErr"/>.
11892	</para>
11893	</listitem>
11894
11895	<listitem>
11896	<para>
11897	Controller-specific error completion with error information
11898	indicating transmission error.
11899	</para>
11900	</listitem>
11901
11902	<listitem>
11903	<para>
11904	On some controllers, command timeout.  In this case, there may
11905	be a mechanism to determine that the timeout is due to
11906	transmission error.
11907	</para>
11908	</listitem>
11909
11910	<listitem>
11911	<para>
11912	Unknown/random errors, timeouts and all sorts of weirdities.
11913	</para>
11914	</listitem>
11915
11916	</itemizedlist>
11917
11918	<para>
11919	As described above, transmission errors can cause wide variety
11920	of symptoms ranging from device ICRC error to random device
11921	lockup, and, for many cases, there is no way to tell if an
11922	error condition is due to transmission error or not;
11923	therefore, it's necessary to employ some kind of heuristic
11924	when dealing with errors and timeouts.  For example,
11925	encountering repetitive ABRT errors for known supported
11926	command is likely to indicate ATA bus error.
11927	</para>
11928
11929	<para>
11930	Once it's determined that ATA bus errors have possibly
11931	occurred, lowering ATA bus transmission speed is one of
11932	actions which may alleviate the problem.  See <xref
11933	linkend="exrecReconf"/> for more information.
11934	</para>
11935
11936     </sect2>
11937
11938     <sect2 id="excatPCIbusErr">
11939        <title>PCI bus error</title>
11940
11941	<para>
11942	Data corruption or other failures during transmission over PCI
11943	(or other system bus).  For standard BMDMA, this is indicated
11944	by Error bit in the BMDMA Status register.  This type of
11945	errors must be logged as it indicates something is very wrong
11946	with the system.  Resetting host controller is recommended.
11947	</para>
11948
11949     </sect2>
11950
11951     <sect2 id="excatLateCompletion">
11952        <title>Late completion</title>
11953
11954	<para>
11955	This occurs when timeout occurs and the timeout handler finds
11956	out that the timed out command has completed successfully or
11957	with error.  This is usually caused by lost interrupts.  This
11958	type of errors must be logged.  Resetting host controller is
11959	recommended.
11960	</para>
11961
11962     </sect2>
11963
11964     <sect2 id="excatUnknown">
11965        <title>Unknown error (timeout)</title>
11966
11967	<para>
11968	This is when timeout occurs and the command is still
11969	processing or the host and device are in unknown state.  When
11970	this occurs, HSM could be in any valid or invalid state.  To
11971	bring the device to known state and make it forget about the
11972	timed out command, resetting is necessary.  The timed out
11973	command may be retried.
11974	</para>
11975
11976	<para>
11977	Timeouts can also be caused by transmission errors.  Refer to
11978	<xref linkend="excatATAbusErr"/> for more details.
11979	</para>
11980
11981     </sect2>
11982
11983     <sect2 id="excatHoplugPM">
11984        <title>Hotplug and power management exceptions</title>
11985
11986	<para>
11987	&lt;&lt;TODO: fill here&gt;&gt;
11988	</para>
11989
11990     </sect2>
11991
11992  </sect1>
11993
11994  <sect1 id="exrec">
11995     <title>EH recovery actions</title>
11996
11997     <para>
11998     This section discusses several important recovery actions.
11999     </para>
12000
12001     <sect2 id="exrecClr">
12002        <title>Clearing error condition</title>
12003
12004	<para>
12005	Many controllers require its error registers to be cleared by
12006	error handler.  Different controllers may have different
12007	requirements.
12008	</para>
12009
12010	<para>
12011	For SATA, it's strongly recommended to clear at least SError
12012	register during error handling.
12013	</para>
12014     </sect2>
12015
12016     <sect2 id="exrecRst">
12017        <title>Reset</title>
12018
12019	<para>
12020	During EH, resetting is necessary in the following cases.
12021	</para>
12022
12023	<itemizedlist>
12024
12025	<listitem>
12026	<para>
12027	HSM is in unknown or invalid state
12028	</para>
12029	</listitem>
12030
12031	<listitem>
12032	<para>
12033	HBA is in unknown or invalid state
12034	</para>
12035	</listitem>
12036
12037	<listitem>
12038	<para>
12039	EH needs to make HBA/device forget about in-flight commands
12040	</para>
12041	</listitem>
12042
12043	<listitem>
12044	<para>
12045	HBA/device behaves weirdly
12046	</para>
12047	</listitem>
12048
12049	</itemizedlist>
12050
12051	<para>
12052	Resetting during EH might be a good idea regardless of error
12053	condition to improve EH robustness.  Whether to reset both or
12054	either one of HBA and device depends on situation but the
12055	following scheme is recommended.
12056	</para>
12057
12058	<itemizedlist>
12059
12060	<listitem>
12061	<para>
12062	When it's known that HBA is in ready state but ATA/ATAPI
12063	device is in unknown state, reset only device.
12064	</para>
12065	</listitem>
12066
12067	<listitem>
12068	<para>
12069	If HBA is in unknown state, reset both HBA and device.
12070	</para>
12071	</listitem>
12072
12073	</itemizedlist>
12074
12075	<para>
12076	HBA resetting is implementation specific.  For a controller
12077	complying to taskfile/BMDMA PCI IDE, stopping active DMA
12078	transaction may be sufficient iff BMDMA state is the only HBA
12079	context.  But even mostly taskfile/BMDMA PCI IDE complying
12080	controllers may have implementation specific requirements and
12081	mechanism to reset themselves.  This must be addressed by
12082	specific drivers.
12083	</para>
12084
12085	<para>
12086	OTOH, ATA/ATAPI standard describes in detail ways to reset
12087	ATA/ATAPI devices.
12088	</para>
12089
12090	<variablelist>
12091
12092	   <varlistentry><term>PATA hardware reset</term>
12093	   <listitem>
12094	   <para>
12095	   This is hardware initiated device reset signalled with
12096	   asserted PATA RESET- signal.  There is no standard way to
12097	   initiate hardware reset from software although some
12098	   hardware provides registers that allow driver to directly
12099	   tweak the RESET- signal.
12100	   </para>
12101	   </listitem>
12102	   </varlistentry>
12103
12104	   <varlistentry><term>Software reset</term>
12105	   <listitem>
12106	   <para>
12107	   This is achieved by turning CONTROL SRST bit on for at
12108	   least 5us.  Both PATA and SATA support it but, in case of
12109	   SATA, this may require controller-specific support as the
12110	   second Register FIS to clear SRST should be transmitted
12111	   while BSY bit is still set.  Note that on PATA, this resets
12112	   both master and slave devices on a channel.
12113	   </para>
12114	   </listitem>
12115	   </varlistentry>
12116
12117	   <varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term>
12118	   <listitem>
12119	   <para>
12120	   Although ATA/ATAPI standard doesn't describe exactly, EDD
12121	   implies some level of resetting, possibly similar level
12122	   with software reset.  Host-side EDD protocol can be handled
12123	   with normal command processing and most SATA controllers
12124	   should be able to handle EDD's just like other commands.
12125	   As in software reset, EDD affects both devices on a PATA
12126	   bus.
12127	   </para>
12128	   <para>
12129	   Although EDD does reset devices, this doesn't suit error
12130	   handling as EDD cannot be issued while BSY is set and it's
12131	   unclear how it will act when device is in unknown/weird
12132	   state.
12133	   </para>
12134	   </listitem>
12135	   </varlistentry>
12136
12137	   <varlistentry><term>ATAPI DEVICE RESET command</term>
12138	   <listitem>
12139	   <para>
12140	   This is very similar to software reset except that reset
12141	   can be restricted to the selected device without affecting
12142	   the other device sharing the cable.
12143	   </para>
12144	   </listitem>
12145	   </varlistentry>
12146
12147	   <varlistentry><term>SATA phy reset</term>
12148	   <listitem>
12149	   <para>
12150	   This is the preferred way of resetting a SATA device.  In
12151	   effect, it's identical to PATA hardware reset.  Note that
12152	   this can be done with the standard SCR Control register.
12153	   As such, it's usually easier to implement than software
12154	   reset.
12155	   </para>
12156	   </listitem>
12157	   </varlistentry>
12158
12159	</variablelist>
12160
12161	<para>
12162	One more thing to consider when resetting devices is that
12163	resetting clears certain configuration parameters and they
12164	need to be set to their previous or newly adjusted values
12165	after reset.
12166	</para>
12167
12168	<para>
12169	Parameters affected are.
12170	</para>
12171
12172	<itemizedlist>
12173
12174	<listitem>
12175	<para>
12176	CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
12177	</para>
12178	</listitem>
12179
12180	<listitem>
12181	<para>
12182	Parameters set with SET FEATURES including transfer mode setting
12183	</para>
12184	</listitem>
12185
12186	<listitem>
12187	<para>
12188	Block count set with SET MULTIPLE MODE
12189	</para>
12190	</listitem>
12191
12192	<listitem>
12193	<para>
12194	Other parameters (SET MAX, MEDIA LOCK...)
12195	</para>
12196	</listitem>
12197
12198	</itemizedlist>
12199
12200	<para>
12201	ATA/ATAPI standard specifies that some parameters must be
12202	maintained across hardware or software reset, but doesn't
12203	strictly specify all of them.  Always reconfiguring needed
12204	parameters after reset is required for robustness.  Note that
12205	this also applies when resuming from deep sleep (power-off).
12206	</para>
12207
12208	<para>
12209	Also, ATA/ATAPI standard requires that IDENTIFY DEVICE /
12210	IDENTIFY PACKET DEVICE is issued after any configuration
12211	parameter is updated or a hardware reset and the result used
12212	for further operation.  OS driver is required to implement
12213	revalidation mechanism to support this.
12214	</para>
12215
12216     </sect2>
12217
12218     <sect2 id="exrecReconf">
12219        <title>Reconfigure transport</title>
12220
12221	<para>
12222	For both PATA and SATA, a lot of corners are cut for cheap
12223	connectors, cables or controllers and it's quite common to see
12224	high transmission error rate.  This can be mitigated by
12225	lowering transmission speed.
12226	</para>
12227
12228	<para>
12229	The following is a possible scheme Jeff Garzik suggested.
12230	</para>
12231
12232	<blockquote>
12233	<para>
12234	If more than $N (3?) transmission errors happen in 15 minutes,
12235	</para>	
12236	<itemizedlist>
12237	<listitem>
12238	<para>
12239	if SATA, decrease SATA PHY speed.  if speed cannot be decreased,
12240	</para>
12241	</listitem>
12242	<listitem>
12243	<para>
12244	decrease UDMA xfer speed.  if at UDMA0, switch to PIO4,
12245	</para>
12246	</listitem>
12247	<listitem>
12248	<para>
12249	decrease PIO xfer speed.  if at PIO3, complain, but continue
12250	</para>
12251	</listitem>
12252	</itemizedlist>
12253	</blockquote>
12254
12255     </sect2>
12256
12257  </sect1>
12258
12259  </chapter>
12260
12261  <chapter id="PiixInt">
12262     <title>ata_piix Internals</title>
12263<!-- drivers/ata/ata_piix.c -->
12264<refentry id="API-ich-pata-cable-detect">
12265<refentryinfo>
12266 <title>LINUX</title>
12267 <productname>Kernel Hackers Manual</productname>
12268 <date>July 2017</date>
12269</refentryinfo>
12270<refmeta>
12271 <refentrytitle><phrase>ich_pata_cable_detect</phrase></refentrytitle>
12272 <manvolnum>9</manvolnum>
12273 <refmiscinfo class="version">4.1.27</refmiscinfo>
12274</refmeta>
12275<refnamediv>
12276 <refname>ich_pata_cable_detect</refname>
12277 <refpurpose>
12278  Probe host controller cable detect info
12279 </refpurpose>
12280</refnamediv>
12281<refsynopsisdiv>
12282 <title>Synopsis</title>
12283  <funcsynopsis><funcprototype>
12284   <funcdef>int <function>ich_pata_cable_detect </function></funcdef>
12285   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
12286  </funcprototype></funcsynopsis>
12287</refsynopsisdiv>
12288<refsect1>
12289 <title>Arguments</title>
12290 <variablelist>
12291  <varlistentry>
12292   <term><parameter>ap</parameter></term>
12293   <listitem>
12294    <para>
12295     Port for which cable detect info is desired
12296    </para>
12297   </listitem>
12298  </varlistentry>
12299 </variablelist>
12300</refsect1>
12301<refsect1>
12302<title>Description</title>
12303<para>
12304   Read 80c cable indicator from ATA PCI device's PCI config
12305   register.  This register is normally set by firmware (BIOS).
12306</para>
12307</refsect1>
12308<refsect1>
12309<title>LOCKING</title>
12310<para>
12311   None (inherited from caller).
12312</para>
12313</refsect1>
12314</refentry>
12315
12316<refentry id="API-piix-pata-prereset">
12317<refentryinfo>
12318 <title>LINUX</title>
12319 <productname>Kernel Hackers Manual</productname>
12320 <date>July 2017</date>
12321</refentryinfo>
12322<refmeta>
12323 <refentrytitle><phrase>piix_pata_prereset</phrase></refentrytitle>
12324 <manvolnum>9</manvolnum>
12325 <refmiscinfo class="version">4.1.27</refmiscinfo>
12326</refmeta>
12327<refnamediv>
12328 <refname>piix_pata_prereset</refname>
12329 <refpurpose>
12330     prereset for PATA host controller
12331 </refpurpose>
12332</refnamediv>
12333<refsynopsisdiv>
12334 <title>Synopsis</title>
12335  <funcsynopsis><funcprototype>
12336   <funcdef>int <function>piix_pata_prereset </function></funcdef>
12337   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
12338   <paramdef>unsigned long <parameter>deadline</parameter></paramdef>
12339  </funcprototype></funcsynopsis>
12340</refsynopsisdiv>
12341<refsect1>
12342 <title>Arguments</title>
12343 <variablelist>
12344  <varlistentry>
12345   <term><parameter>link</parameter></term>
12346   <listitem>
12347    <para>
12348     Target link
12349    </para>
12350   </listitem>
12351  </varlistentry>
12352  <varlistentry>
12353   <term><parameter>deadline</parameter></term>
12354   <listitem>
12355    <para>
12356     deadline jiffies for the operation
12357    </para>
12358   </listitem>
12359  </varlistentry>
12360 </variablelist>
12361</refsect1>
12362<refsect1>
12363<title>LOCKING</title>
12364<para>
12365   None (inherited from caller).
12366</para>
12367</refsect1>
12368</refentry>
12369
12370<refentry id="API-piix-set-piomode">
12371<refentryinfo>
12372 <title>LINUX</title>
12373 <productname>Kernel Hackers Manual</productname>
12374 <date>July 2017</date>
12375</refentryinfo>
12376<refmeta>
12377 <refentrytitle><phrase>piix_set_piomode</phrase></refentrytitle>
12378 <manvolnum>9</manvolnum>
12379 <refmiscinfo class="version">4.1.27</refmiscinfo>
12380</refmeta>
12381<refnamediv>
12382 <refname>piix_set_piomode</refname>
12383 <refpurpose>
12384     Initialize host controller PATA PIO timings
12385 </refpurpose>
12386</refnamediv>
12387<refsynopsisdiv>
12388 <title>Synopsis</title>
12389  <funcsynopsis><funcprototype>
12390   <funcdef>void <function>piix_set_piomode </function></funcdef>
12391   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
12392   <paramdef>struct ata_device * <parameter>adev</parameter></paramdef>
12393  </funcprototype></funcsynopsis>
12394</refsynopsisdiv>
12395<refsect1>
12396 <title>Arguments</title>
12397 <variablelist>
12398  <varlistentry>
12399   <term><parameter>ap</parameter></term>
12400   <listitem>
12401    <para>
12402     Port whose timings we are configuring
12403    </para>
12404   </listitem>
12405  </varlistentry>
12406  <varlistentry>
12407   <term><parameter>adev</parameter></term>
12408   <listitem>
12409    <para>
12410     Drive in question
12411    </para>
12412   </listitem>
12413  </varlistentry>
12414 </variablelist>
12415</refsect1>
12416<refsect1>
12417<title>Description</title>
12418<para>
12419   Set PIO mode for device, in host controller PCI config space.
12420</para>
12421</refsect1>
12422<refsect1>
12423<title>LOCKING</title>
12424<para>
12425   None (inherited from caller).
12426</para>
12427</refsect1>
12428</refentry>
12429
12430<refentry id="API-do-pata-set-dmamode">
12431<refentryinfo>
12432 <title>LINUX</title>
12433 <productname>Kernel Hackers Manual</productname>
12434 <date>July 2017</date>
12435</refentryinfo>
12436<refmeta>
12437 <refentrytitle><phrase>do_pata_set_dmamode</phrase></refentrytitle>
12438 <manvolnum>9</manvolnum>
12439 <refmiscinfo class="version">4.1.27</refmiscinfo>
12440</refmeta>
12441<refnamediv>
12442 <refname>do_pata_set_dmamode</refname>
12443 <refpurpose>
12444     Initialize host controller PATA PIO timings
12445 </refpurpose>
12446</refnamediv>
12447<refsynopsisdiv>
12448 <title>Synopsis</title>
12449  <funcsynopsis><funcprototype>
12450   <funcdef>void <function>do_pata_set_dmamode </function></funcdef>
12451   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
12452   <paramdef>struct ata_device * <parameter>adev</parameter></paramdef>
12453   <paramdef>int <parameter>isich</parameter></paramdef>
12454  </funcprototype></funcsynopsis>
12455</refsynopsisdiv>
12456<refsect1>
12457 <title>Arguments</title>
12458 <variablelist>
12459  <varlistentry>
12460   <term><parameter>ap</parameter></term>
12461   <listitem>
12462    <para>
12463     Port whose timings we are configuring
12464    </para>
12465   </listitem>
12466  </varlistentry>
12467  <varlistentry>
12468   <term><parameter>adev</parameter></term>
12469   <listitem>
12470    <para>
12471     Drive in question
12472    </para>
12473   </listitem>
12474  </varlistentry>
12475  <varlistentry>
12476   <term><parameter>isich</parameter></term>
12477   <listitem>
12478    <para>
12479     set if the chip is an ICH device
12480    </para>
12481   </listitem>
12482  </varlistentry>
12483 </variablelist>
12484</refsect1>
12485<refsect1>
12486<title>Description</title>
12487<para>
12488   Set UDMA mode for device, in host controller PCI config space.
12489</para>
12490</refsect1>
12491<refsect1>
12492<title>LOCKING</title>
12493<para>
12494   None (inherited from caller).
12495</para>
12496</refsect1>
12497</refentry>
12498
12499<refentry id="API-piix-set-dmamode">
12500<refentryinfo>
12501 <title>LINUX</title>
12502 <productname>Kernel Hackers Manual</productname>
12503 <date>July 2017</date>
12504</refentryinfo>
12505<refmeta>
12506 <refentrytitle><phrase>piix_set_dmamode</phrase></refentrytitle>
12507 <manvolnum>9</manvolnum>
12508 <refmiscinfo class="version">4.1.27</refmiscinfo>
12509</refmeta>
12510<refnamediv>
12511 <refname>piix_set_dmamode</refname>
12512 <refpurpose>
12513     Initialize host controller PATA DMA timings
12514 </refpurpose>
12515</refnamediv>
12516<refsynopsisdiv>
12517 <title>Synopsis</title>
12518  <funcsynopsis><funcprototype>
12519   <funcdef>void <function>piix_set_dmamode </function></funcdef>
12520   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
12521   <paramdef>struct ata_device * <parameter>adev</parameter></paramdef>
12522  </funcprototype></funcsynopsis>
12523</refsynopsisdiv>
12524<refsect1>
12525 <title>Arguments</title>
12526 <variablelist>
12527  <varlistentry>
12528   <term><parameter>ap</parameter></term>
12529   <listitem>
12530    <para>
12531     Port whose timings we are configuring
12532    </para>
12533   </listitem>
12534  </varlistentry>
12535  <varlistentry>
12536   <term><parameter>adev</parameter></term>
12537   <listitem>
12538    <para>
12539     um
12540    </para>
12541   </listitem>
12542  </varlistentry>
12543 </variablelist>
12544</refsect1>
12545<refsect1>
12546<title>Description</title>
12547<para>
12548   Set MW/UDMA mode for device, in host controller PCI config space.
12549</para>
12550</refsect1>
12551<refsect1>
12552<title>LOCKING</title>
12553<para>
12554   None (inherited from caller).
12555</para>
12556</refsect1>
12557</refentry>
12558
12559<refentry id="API-ich-set-dmamode">
12560<refentryinfo>
12561 <title>LINUX</title>
12562 <productname>Kernel Hackers Manual</productname>
12563 <date>July 2017</date>
12564</refentryinfo>
12565<refmeta>
12566 <refentrytitle><phrase>ich_set_dmamode</phrase></refentrytitle>
12567 <manvolnum>9</manvolnum>
12568 <refmiscinfo class="version">4.1.27</refmiscinfo>
12569</refmeta>
12570<refnamediv>
12571 <refname>ich_set_dmamode</refname>
12572 <refpurpose>
12573     Initialize host controller PATA DMA timings
12574 </refpurpose>
12575</refnamediv>
12576<refsynopsisdiv>
12577 <title>Synopsis</title>
12578  <funcsynopsis><funcprototype>
12579   <funcdef>void <function>ich_set_dmamode </function></funcdef>
12580   <paramdef>struct ata_port * <parameter>ap</parameter></paramdef>
12581   <paramdef>struct ata_device * <parameter>adev</parameter></paramdef>
12582  </funcprototype></funcsynopsis>
12583</refsynopsisdiv>
12584<refsect1>
12585 <title>Arguments</title>
12586 <variablelist>
12587  <varlistentry>
12588   <term><parameter>ap</parameter></term>
12589   <listitem>
12590    <para>
12591     Port whose timings we are configuring
12592    </para>
12593   </listitem>
12594  </varlistentry>
12595  <varlistentry>
12596   <term><parameter>adev</parameter></term>
12597   <listitem>
12598    <para>
12599     um
12600    </para>
12601   </listitem>
12602  </varlistentry>
12603 </variablelist>
12604</refsect1>
12605<refsect1>
12606<title>Description</title>
12607<para>
12608   Set MW/UDMA mode for device, in host controller PCI config space.
12609</para>
12610</refsect1>
12611<refsect1>
12612<title>LOCKING</title>
12613<para>
12614   None (inherited from caller).
12615</para>
12616</refsect1>
12617</refentry>
12618
12619<refentry id="API-piix-check-450nx-errata">
12620<refentryinfo>
12621 <title>LINUX</title>
12622 <productname>Kernel Hackers Manual</productname>
12623 <date>July 2017</date>
12624</refentryinfo>
12625<refmeta>
12626 <refentrytitle><phrase>piix_check_450nx_errata</phrase></refentrytitle>
12627 <manvolnum>9</manvolnum>
12628 <refmiscinfo class="version">4.1.27</refmiscinfo>
12629</refmeta>
12630<refnamediv>
12631 <refname>piix_check_450nx_errata</refname>
12632 <refpurpose>
12633     Check for problem 450NX setup
12634 </refpurpose>
12635</refnamediv>
12636<refsynopsisdiv>
12637 <title>Synopsis</title>
12638  <funcsynopsis><funcprototype>
12639   <funcdef>int <function>piix_check_450nx_errata </function></funcdef>
12640   <paramdef>struct pci_dev * <parameter>ata_dev</parameter></paramdef>
12641  </funcprototype></funcsynopsis>
12642</refsynopsisdiv>
12643<refsect1>
12644 <title>Arguments</title>
12645 <variablelist>
12646  <varlistentry>
12647   <term><parameter>ata_dev</parameter></term>
12648   <listitem>
12649    <para>
12650     the PCI device to check
12651    </para>
12652   </listitem>
12653  </varlistentry>
12654 </variablelist>
12655</refsect1>
12656<refsect1>
12657<title>Description</title>
12658<para>
12659   Check for the present of 450NX errata #19 and errata #25. If
12660   they are found return an error code so we can turn off DMA
12661</para>
12662</refsect1>
12663</refentry>
12664
12665<refentry id="API-piix-init-one">
12666<refentryinfo>
12667 <title>LINUX</title>
12668 <productname>Kernel Hackers Manual</productname>
12669 <date>July 2017</date>
12670</refentryinfo>
12671<refmeta>
12672 <refentrytitle><phrase>piix_init_one</phrase></refentrytitle>
12673 <manvolnum>9</manvolnum>
12674 <refmiscinfo class="version">4.1.27</refmiscinfo>
12675</refmeta>
12676<refnamediv>
12677 <refname>piix_init_one</refname>
12678 <refpurpose>
12679     Register PIIX ATA PCI device with kernel services
12680 </refpurpose>
12681</refnamediv>
12682<refsynopsisdiv>
12683 <title>Synopsis</title>
12684  <funcsynopsis><funcprototype>
12685   <funcdef>int <function>piix_init_one </function></funcdef>
12686   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
12687   <paramdef>const struct pci_device_id * <parameter>ent</parameter></paramdef>
12688  </funcprototype></funcsynopsis>
12689</refsynopsisdiv>
12690<refsect1>
12691 <title>Arguments</title>
12692 <variablelist>
12693  <varlistentry>
12694   <term><parameter>pdev</parameter></term>
12695   <listitem>
12696    <para>
12697     PCI device to register
12698    </para>
12699   </listitem>
12700  </varlistentry>
12701  <varlistentry>
12702   <term><parameter>ent</parameter></term>
12703   <listitem>
12704    <para>
12705     Entry in piix_pci_tbl matching with <parameter>pdev</parameter>
12706    </para>
12707   </listitem>
12708  </varlistentry>
12709 </variablelist>
12710</refsect1>
12711<refsect1>
12712<title>Description</title>
12713<para>
12714   Called from kernel PCI layer.  We probe for combined mode (sigh),
12715   and then hand over control to libata, for it to do the rest.
12716</para>
12717</refsect1>
12718<refsect1>
12719<title>LOCKING</title>
12720<para>
12721   Inherited from PCI layer (may sleep).
12722</para>
12723</refsect1>
12724<refsect1>
12725<title>RETURNS</title>
12726<para>
12727   Zero on success, or -ERRNO value.
12728</para>
12729</refsect1>
12730</refentry>
12731
12732  </chapter>
12733
12734  <chapter id="SILInt">
12735     <title>sata_sil Internals</title>
12736<!-- drivers/ata/sata_sil.c -->
12737<refentry id="API-sil-set-mode">
12738<refentryinfo>
12739 <title>LINUX</title>
12740 <productname>Kernel Hackers Manual</productname>
12741 <date>July 2017</date>
12742</refentryinfo>
12743<refmeta>
12744 <refentrytitle><phrase>sil_set_mode</phrase></refentrytitle>
12745 <manvolnum>9</manvolnum>
12746 <refmiscinfo class="version">4.1.27</refmiscinfo>
12747</refmeta>
12748<refnamediv>
12749 <refname>sil_set_mode</refname>
12750 <refpurpose>
12751  wrap set_mode functions
12752 </refpurpose>
12753</refnamediv>
12754<refsynopsisdiv>
12755 <title>Synopsis</title>
12756  <funcsynopsis><funcprototype>
12757   <funcdef>int <function>sil_set_mode </function></funcdef>
12758   <paramdef>struct ata_link * <parameter>link</parameter></paramdef>
12759   <paramdef>struct ata_device ** <parameter>r_failed</parameter></paramdef>
12760  </funcprototype></funcsynopsis>
12761</refsynopsisdiv>
12762<refsect1>
12763 <title>Arguments</title>
12764 <variablelist>
12765  <varlistentry>
12766   <term><parameter>link</parameter></term>
12767   <listitem>
12768    <para>
12769     link to set up
12770    </para>
12771   </listitem>
12772  </varlistentry>
12773  <varlistentry>
12774   <term><parameter>r_failed</parameter></term>
12775   <listitem>
12776    <para>
12777     returned device when we fail
12778    </para>
12779   </listitem>
12780  </varlistentry>
12781 </variablelist>
12782</refsect1>
12783<refsect1>
12784<title>Description</title>
12785<para>
12786   Wrap the libata method for device setup as after the setup we need
12787   to inspect the results and do some configuration work
12788</para>
12789</refsect1>
12790</refentry>
12791
12792<refentry id="API-sil-dev-config">
12793<refentryinfo>
12794 <title>LINUX</title>
12795 <productname>Kernel Hackers Manual</productname>
12796 <date>July 2017</date>
12797</refentryinfo>
12798<refmeta>
12799 <refentrytitle><phrase>sil_dev_config</phrase></refentrytitle>
12800 <manvolnum>9</manvolnum>
12801 <refmiscinfo class="version">4.1.27</refmiscinfo>
12802</refmeta>
12803<refnamediv>
12804 <refname>sil_dev_config</refname>
12805 <refpurpose>
12806     Apply device/host-specific errata fixups
12807 </refpurpose>
12808</refnamediv>
12809<refsynopsisdiv>
12810 <title>Synopsis</title>
12811  <funcsynopsis><funcprototype>
12812   <funcdef>void <function>sil_dev_config </function></funcdef>
12813   <paramdef>struct ata_device * <parameter>dev</parameter></paramdef>
12814  </funcprototype></funcsynopsis>
12815</refsynopsisdiv>
12816<refsect1>
12817 <title>Arguments</title>
12818 <variablelist>
12819  <varlistentry>
12820   <term><parameter>dev</parameter></term>
12821   <listitem>
12822    <para>
12823     Device to be examined
12824    </para>
12825   </listitem>
12826  </varlistentry>
12827 </variablelist>
12828</refsect1>
12829<refsect1>
12830<title>Description</title>
12831<para>
12832   After the IDENTIFY [PACKET] DEVICE step is complete, and a
12833   device is known to be present, this function is called.
12834   We apply two errata fixups which are specific to Silicon Image,
12835   a Seagate and a Maxtor fixup.
12836   </para><para>
12837
12838   For certain Seagate devices, we must limit the maximum sectors
12839   to under 8K.
12840   </para><para>
12841
12842   For certain Maxtor devices, we must not program the drive
12843   beyond udma5.
12844   </para><para>
12845
12846   Both fixups are unfairly pessimistic.  As soon as I get more
12847   information on these errata, I will create a more exhaustive
12848   list, and apply the fixups to only the specific
12849   devices/hosts/firmwares that need it.
12850   </para><para>
12851
12852   20040111 - Seagate drives affected by the Mod15Write bug are blacklisted
12853   The Maxtor quirk is in the blacklist, but I'm keeping the original
12854   pessimistic fix for the following reasons...
12855   - There seems to be less info on it, only one device gleaned off the
12856   Windows	driver, maybe only one is affected.  More info would be greatly
12857   appreciated.
12858   - But then again UDMA5 is hardly anything to complain about
12859</para>
12860</refsect1>
12861</refentry>
12862
12863  </chapter>
12864
12865  <chapter id="libataThanks">
12866     <title>Thanks</title>
12867  <para>
12868  The bulk of the ATA knowledge comes thanks to long conversations with
12869  Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
12870  and SCSI specifications.
12871  </para>
12872  <para>
12873  Thanks to Alan Cox for pointing out similarities 
12874  between SATA and SCSI, and in general for motivation to hack on
12875  libata.
12876  </para>
12877  <para>
12878  libata's device detection
12879  method, ata_pio_devchk, and in general all the early probing was
12880  based on extensive study of Hale Landis's probe/reset code in his
12881  ATADRVR driver (www.ata-atapi.com).
12882  </para>
12883  </chapter>
12884
12885</book>
12886