Merge of 'docs' branch from (31760463) · Commits · e / devices / android_kernel_fairphone_FP4

Documentation/DocBook/libata.tmpl

+124 −32

Original line number	Diff line number	Diff line
		@@ -14,7 +14,7 @@
		</authorgroup>

		<copyright>
		<year>2003</year>
		<year>2003-2005</year>
		<holder>Jeff Garzik</holder>
		</copyright>

		@@ -44,30 +44,38 @@

		<toc></toc>

		<chapter id="libataThanks">
		<title>Thanks</title>
		<para>
		The bulk of the ATA knowledge comes thanks to long conversations with
		Andre Hedrick (www.linux-ide.org).
		</para>
		<chapter id="libataIntroduction">
		<title>Introduction</title>
		<para>
		Thanks to Alan Cox for pointing out similarities
		between SATA and SCSI, and in general for motivation to hack on
		libata.
		libATA is a library used inside the Linux kernel to support ATA host
		controllers and devices. libATA provides an ATA driver API, class
		transports for ATA and ATAPI devices, and SCSI<->ATA translation
		for ATA devices according to the T10 SAT specification.
		</para>
		<para>
		libata's device detection
		method, ata_pio_devchk, and in general all the early probing was
		based on extensive study of Hale Landis's probe/reset code in his
		ATADRVR driver (www.ata-atapi.com).
		This Guide documents the libATA driver API, library functions, library
		internals, and a couple sample ATA low-level drivers.
		</para>
		</chapter>

		<chapter id="libataDriverApi">
		<title>libata Driver API</title>
		<para>
		struct ata_port_operations is defined for every low-level libata
		hardware driver, and it controls how the low-level driver
		interfaces with the ATA and SCSI layers.
		</para>
		<para>
		FIS-based drivers will hook into the system with ->qc_prep() and
		->qc_issue() high-level hooks. Hardware which behaves in a manner
		similar to PCI IDE hardware may utilize several generic helpers,
		defining at a bare minimum the bus I/O addresses of the ATA shadow
		register blocks.
		</para>
		<sect1>
		<title>struct ata_port_operations</title>

		<sect2><title>Disable ATA port</title>
		<programlisting>
		void (port_disable) (struct ata_port );
		</programlisting>
		@@ -78,6 +86,9 @@ void (port_disable) (struct ata_port );
		unplug).
		</para>

		</sect2>

		<sect2><title>Post-IDENTIFY device configuration</title>
		<programlisting>
		void (dev_config) (struct ata_port , struct ata_device *);
		</programlisting>
		@@ -88,6 +99,9 @@ void (dev_config) (struct ata_port , struct ata_device *);
		issue of SET FEATURES - XFER MODE, and prior to operation.
		</para>

		</sect2>

		<sect2><title>Set PIO/DMA mode</title>
		<programlisting>
		void (set_piomode) (struct ata_port , struct ata_device *);
		void (set_dmamode) (struct ata_port , struct ata_device *);
		@@ -108,6 +122,9 @@ void (post_set_mode) (struct ata_port ap);
		->set_dma_mode() is only called if DMA is possible.
		</para>

		</sect2>

		<sect2><title>Taskfile read/write</title>
		<programlisting>
		void (tf_load) (struct ata_port ap, struct ata_taskfile *tf);
		void (tf_read) (struct ata_port ap, struct ata_taskfile *tf);
		@@ -120,6 +137,9 @@ void (tf_read) (struct ata_port ap, struct ata_taskfile *tf);
		taskfile register values.
		</para>

		</sect2>

		<sect2><title>ATA command execute</title>
		<programlisting>
		void (exec_command)(struct ata_port ap, struct ata_taskfile *tf);
		</programlisting>
		@@ -129,17 +149,37 @@ void (exec_command)(struct ata_port ap, struct ata_taskfile *tf);
		->tf_load(), to be initiated in hardware.
		</para>

		</sect2>

		<sect2><title>Per-cmd ATAPI DMA capabilities filter</title>
		<programlisting>
		int (check_atapi_dma) (struct ata_queued_cmd qc);
		</programlisting>

		<para>
		Allow low-level driver to filter ATA PACKET commands, returning a status
		indicating whether or not it is OK to use DMA for the supplied PACKET
		command.
		</para>

		</sect2>

		<sect2><title>Read specific ATA shadow registers</title>
		<programlisting>
		u8 (check_status)(struct ata_port ap);
		void (dev_select)(struct ata_port ap, unsigned int device);
		u8 (check_altstatus)(struct ata_port ap);
		u8 (check_err)(struct ata_port ap);
		</programlisting>

		<para>
		Reads the Status ATA shadow register from hardware. On some
		hardware, this has the side effect of clearing the interrupt
		condition.
		Reads the Status/AltStatus/Error ATA shadow register from
		hardware. On some hardware, reading the Status register has
		the side effect of clearing the interrupt condition.
		</para>

		</sect2>

		<sect2><title>Select ATA device on bus</title>
		<programlisting>
		void (dev_select)(struct ata_port ap, unsigned int device);
		</programlisting>
		@@ -147,9 +187,13 @@ void (dev_select)(struct ata_port ap, unsigned int device);
		<para>
		Issues the low-level hardware command(s) that causes one of N
		hardware devices to be considered 'selected' (active and
		available for use) on the ATA bus.
		available for use) on the ATA bus. This generally has no
		meaning on FIS-based devices.
		</para>

		</sect2>

		<sect2><title>Reset ATA bus</title>
		<programlisting>
		void (phy_reset) (struct ata_port ap);
		</programlisting>
		@@ -162,17 +206,31 @@ void (phy_reset) (struct ata_port ap);
		functions ata_bus_reset() or sata_phy_reset() for this hook.
		</para>

		</sect2>

		<sect2><title>Control PCI IDE BMDMA engine</title>
		<programlisting>
		void (bmdma_setup) (struct ata_queued_cmd qc);
		void (bmdma_start) (struct ata_queued_cmd qc);
		void (bmdma_stop) (struct ata_port ap);
		u8 (bmdma_status) (struct ata_port ap);
		</programlisting>

		<para>
		When setting up an IDE BMDMA transaction, these hooks arm
		(->bmdma_setup) and fire (->bmdma_start) the hardware's DMA
		engine.
		(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
		the hardware's DMA engine. ->bmdma_status is used to read the standard
		PCI IDE DMA Status register.
		</para>

		<para>
		These hooks are typically either no-ops, or simply not implemented, in
		FIS-based drivers.
		</para>

		</sect2>

		<sect2><title>High-level taskfile hooks</title>
		<programlisting>
		void (qc_prep) (struct ata_queued_cmd qc);
		int (qc_issue) (struct ata_queued_cmd qc);
		@@ -190,20 +248,26 @@ int (qc_issue) (struct ata_queued_cmd qc);
		->qc_issue is used to make a command active, once the hardware
		and S/G tables have been prepared. IDE BMDMA drivers use the
		helper function ata_qc_issue_prot() for taskfile protocol-based
		dispatch. More advanced drivers roll their own ->qc_issue
		implementation, using this as the "issue new ATA command to
		hardware" hook.
		dispatch. More advanced drivers implement their own ->qc_issue.
		</para>

		</sect2>

		<sect2><title>Timeout (error) handling</title>
		<programlisting>
		void (eng_timeout) (struct ata_port ap);
		</programlisting>

		<para>
		This is a high level error handling function, called from the
		error handling thread, when a command times out.
		error handling thread, when a command times out. Most newer
		hardware will implement its own error handling code here. IDE BMDMA
		drivers may use the helper function ata_eng_timeout().
		</para>

		</sect2>

		<sect2><title>Hardware interrupt handling</title>
		<programlisting>
		irqreturn_t (irq_handler)(int, void , struct pt_regs *);
		void (irq_clear) (struct ata_port );
		@@ -216,6 +280,9 @@ void (irq_clear) (struct ata_port );
		is quiet.
		</para>

		</sect2>

		<sect2><title>SATA phy read/write</title>
		<programlisting>
		u32 (scr_read) (struct ata_port ap, unsigned int sc_reg);
		void (scr_write) (struct ata_port ap, unsigned int sc_reg,
		@@ -227,6 +294,9 @@ void (scr_write) (struct ata_port ap, unsigned int sc_reg,
		if ->phy_reset hook called the sata_phy_reset() helper function.
		</para>

		</sect2>

		<sect2><title>Init and shutdown</title>
		<programlisting>
		int (port_start) (struct ata_port ap);
		void (port_stop) (struct ata_port ap);
		@@ -240,15 +310,17 @@ void (host_stop) (struct ata_host_set host_set);
		tasks.
		</para>
		<para>
		->host_stop() is called when the rmmod or hot unplug process
		begins. The hook must stop all hardware interrupts, DMA
		engines, etc.
		</para>
		<para>
		->port_stop() is called after ->host_stop(). It's sole function
		is to release DMA/memory resources, now that they are no longer
		actively being used.
		</para>
		<para>
		->host_stop() is called after all ->port_stop() calls
		have completed. The hook must finalize hardware shutdown, release DMA
		and other resources, etc.
		</para>

		</sect2>

		</sect1>
		</chapter>
		@@ -279,4 +351,24 @@ void (host_stop) (struct ata_host_set host_set);
		!Idrivers/scsi/sata_sil.c
		</chapter>

		<chapter id="libataThanks">
		<title>Thanks</title>
		<para>
		The bulk of the ATA knowledge comes thanks to long conversations with
		Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
		and SCSI specifications.
		</para>
		<para>
		Thanks to Alan Cox for pointing out similarities
		between SATA and SCSI, and in general for motivation to hack on
		libata.
		</para>
		<para>
		libata's device detection
		method, ata_pio_devchk, and in general all the early probing was
		based on extensive study of Hale Landis's probe/reset code in his
		ATADRVR driver (www.ata-atapi.com).
		</para>
		</chapter>

		</book>

drivers/scsi/ata_piix.c

+0 −16

Original line number	Diff line number	Diff line
		@@ -665,15 +665,6 @@ static int piix_init_one (struct pci_dev pdev, const struct pci_device_id ent)
		return ata_pci_init_one(pdev, port_info, n_ports);
		}

		/**
		* piix_init -
		*
		* LOCKING:
		*
		* RETURNS:
		*
		*/

		static int __init piix_init(void)
		{
		int rc;
		@@ -689,13 +680,6 @@ static int __init piix_init(void)
		return 0;
		}

		/**
		* piix_exit -
		*
		* LOCKING:
		*
		*/

		static void __exit piix_exit(void)
		{
		pci_unregister_driver(&piix_pci_driver);

drivers/scsi/libata-core.c

+427 −43

File changed.

Preview size limit exceeded, changes collapsed.

drivers/scsi/libata-scsi.c

+1 −1

Original line number	Diff line number	Diff line
		@@ -947,7 +947,7 @@ unsigned int ata_scsiop_inq_83(struct ata_scsi_args args, u8 rbuf,
		}

		/**
		* ata_scsiop_noop -
		* ata_scsiop_noop - Command handler that simply returns success.
		* @args: device IDENTIFY data / SCSI command of interest.
		* @rbuf: Response buffer, to which simulated SCSI cmd output is sent.
		* @buflen: Response buffer length.

include/linux/libata.h

+58 −0

Original line number	Diff line number	Diff line
		@@ -467,12 +467,34 @@ static inline u8 ata_chk_status(struct ata_port *ap)
		return ap->ops->check_status(ap);
		}


		/**
		* ata_pause - Flush writes and pause 400 nanoseconds.
		* @ap: Port to wait for.
		*
		* LOCKING:
		* Inherited from caller.
		*/

		static inline void ata_pause(struct ata_port *ap)
		{
		ata_altstatus(ap);
		ndelay(400);
		}


		/**
		* ata_busy_wait - Wait for a port status register
		* @ap: Port to wait for.
		*
		* Waits up to max*10 microseconds for the selected bits in the port's
		* status register to be cleared.
		* Returns final value of status register.
		*
		* LOCKING:
		* Inherited from caller.
		*/

		static inline u8 ata_busy_wait(struct ata_port *ap, unsigned int bits,
		unsigned int max)
		{
		@@ -487,6 +509,18 @@ static inline u8 ata_busy_wait(struct ata_port *ap, unsigned int bits,
		return status;
		}


		/**
		* ata_wait_idle - Wait for a port to be idle.
		* @ap: Port to wait for.
		*
		* Waits up to 10ms for port's BUSY and DRQ signals to clear.
		* Returns final value of status register.
		*
		* LOCKING:
		* Inherited from caller.
		*/

		static inline u8 ata_wait_idle(struct ata_port *ap)
		{
		u8 status = ata_busy_wait(ap, ATA_BUSY \| ATA_DRQ, 1000);
		@@ -525,6 +559,18 @@ static inline void ata_tf_init(struct ata_port ap, struct ata_taskfile tf, uns
		tf->device = ATA_DEVICE_OBS \| ATA_DEV1;
		}


		/**
		* ata_irq_on - Enable interrupts on a port.
		* @ap: Port on which interrupts are enabled.
		*
		* Enable interrupts on a legacy IDE device using MMIO or PIO,
		* wait for idle, clear any pending interrupts.
		*
		* LOCKING:
		* Inherited from caller.
		*/

		static inline u8 ata_irq_on(struct ata_port *ap)
		{
		struct ata_ioports *ioaddr = &ap->ioaddr;
		@@ -544,6 +590,18 @@ static inline u8 ata_irq_on(struct ata_port *ap)
		return tmp;
		}


		/**
		* ata_irq_ack - Acknowledge a device interrupt.
		* @ap: Port on which interrupts are enabled.
		*
		* Wait up to 10 ms for legacy IDE device to become idle (BUSY
		* or BUSY+DRQ clear). Obtain dma status and port status from
		* device. Clear the interrupt. Return port status.
		*
		* LOCKING:
		*/

		static inline u8 ata_irq_ack(struct ata_port *ap, unsigned int chk_drq)
		{
		unsigned int bits = chk_drq ? ATA_BUSY \| ATA_DRQ : ATA_BUSY;