USB:Updating the documentation

Documentation from usb.

Signed-off-by: Sakethram Bommisetti <sakethram.bommisetti@stericsson.com>

Conflicts:

	Documentation/DocBook/Makefile

4 files changed, 275 insertions, 5 deletions

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index c19617a55eb..70e985a59db 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -19,8 +19,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
 	    tc_keypad.xml prcmu-fw-api.xml cg2900_fm_radio.xml \
 	    synaptics_rmi4_touchp.xml db5500_keypad.xml \
 	    u5500_LogicalMailbox.xml \
-	    lsm303dlh.xml \
-	    ste_timed_vibra.xml
+	    lsm303dlh.xml ste_timed_vibra.xml ux500_usb.xml
 
 ###
 # The build process is as follows (targets):
diff --git a/Documentation/DocBook/ux500_usb.tmpl b/Documentation/DocBook/ux500_usb.tmpl
new file mode 100644
index 00000000000..f31f3784e93
--- /dev/null
+++ b/Documentation/DocBook/ux500_usb.tmpl
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="USB-FUNCTION-Guide">
+ <bookinfo>
+  <title>USB Driver Function guide</title>
+
+  <authorgroup>
+    <author>
+    <firstname>Praveena</firstname>
+    <surname>Nadahally</surname>
+    <affiliation>
+     <address>
+      <email>praveen.nadahally@stericsson.com</email>
+     </address>
+    </affiliation>
+    </author>
+    <author>
+    <firstname>Rajaram</firstname>
+    <surname>Ragupathy</surname>
+    <affiliation>
+    <address>
+      <email>ragupathy.rajaram@stericsson.com</email>
+        </address>
+    </affiliation>
+    </author>
+    <author>
+    <firstname>SakethRam</firstname>
+    <surname>Bommisetti</surname>
+    <affiliation>
+     <address>
+       <email>sakethram.bommisetti@stericsson.com</email>
+     </address>
+    </affiliation>
+    </author>
+  </authorgroup>
+
+  <copyright>
+   <year>2011</year>
+   <holder>ST-Ericsson</holder>
+  </copyright>
+
+  <subjectset>
+    <subject>
+      <subjectterm>Connectivity</subjectterm>
+    </subject>
+  </subjectset>
+
+  <legalnotice>
+   <para>
+     This documentation is free software; you can redistribute
+     it and/or modify it under the terms of the GNU General Public
+     License version 2 as published by the Free Software Foundation.
+   </para>
+
+   <para>
+     This program is distributed in the hope that it will be
+     useful, but WITHOUT ANY WARRANTY; without even the implied
+     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+     See the GNU General Public License for more details.
+   </para>
+
+   <para>
+     You should have received a copy of the GNU General Public
+     License along with this program; if not, write to the Free
+     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+     MA 02111-1307 USA
+   </para>
+
+   <para>
+     For more details see the file COPYING in the source
+     distribution of Linux.
+   </para>
+
+   </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+  <chapter id="intro">
+    <title>Introduction</title>
+    <para>
+	This documentation describes ST-Ericsson's adaptation on USB external DMA and communication between Mentor USB IP controller and the USB
+	transreceiver
+    </para>
+    </chapter>
+
+ <chapter id="concepts">
+  <title>Concepts</title>
+  <!-- Do NOT change the chapter id or title! -->
+  <para>
+	In ST-Ericsson's USB driver, the open source linux gadget stack and Mentor IP USB 2.0 driver is used. Since the USB Transceiver and Mentor USB IP controller are on different hardware, API's are defined for the communication between them. These API's are available in ux500.c file.
+	The ST-Ericsson's USB driver doesn't have the internal DMA dedicated for USB. So, the external system DMA is used. The integration of external DMA with the mentor chip is available in ux500_dma.c file.
+	Changes have been made in the musb_core.c file where endpoints are configured as per the platform and also integrated DMA specific chnages in the musb_gadget.c file.
+     <!-- TODO: A brief introduction about the concepts
+           which are introduced by the driver.
+           Remove this chapter completely if there are no
+           special concepts introduced by this driver.
+           Do NOT change the chapter id or title! -->
+     <!-- TODO: This guideline for this chapter may be extended
+           during the user-guide guidelines drop. -->
+  </para>
+ </chapter>
+
+ <chapter id="bugs">
+  <title>Known Bugs And Assumptions</title>
+  <!--  Do NOT change the chapter id or title! -->
+  <para>
+    <variablelist>
+
+     <varlistentry>
+      <term>None.</term>
+      <listitem>
+       <para>
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+
+  </para>
+ </chapter>
+
+ <chapter id="intfunctions">
+   <title>Internal Functions Provided</title>
+   <para>
+	List of internal functions
+   </para>
+   <!-- Do NOT change the chapter id or title! -->
+   <!-- TODO: Replace with link to appropriate headerfile(s),
+        source file(s), or both. One per row, ensure the
+        exclamation mark is on the first column! If no
+        appropriate header or source file exist describing a public interface,
+        replace the inclusion with a paragraph containing the text
+        "Not Applicable"-->
+  <section id="ux500_dma.c">
+    <title>ux500_dma.c</title>
+!Idrivers/usb/musb/ux500_dma.c
+  </section>
+  <section id="ux500.c">
+    <title>ux500.c</title>
+!Idrivers/usb/musb/ux500.c
+  </section>
+</chapter>
+
+</book>
diff --git a/drivers/usb/musb/ux500.c b/drivers/usb/musb/ux500.c
index f7e04bf34a1..0806a41f090 100644
--- a/drivers/usb/musb/ux500.c
+++ b/drivers/usb/musb/ux500.c
@@ -35,6 +35,12 @@ struct ux500_glue {
 };
 #define glue_to_musb(g)	platform_get_drvdata(g->musb)
 
+/**
+ * ux500_musb_init() - Initialize the platform USB driver.
+ * @musb: struct musb pointer.
+ *
+ * This function initialize the USB controller and Phy.
+*/
 static int ux500_musb_init(struct musb *musb)
 {
 	musb->xceiv = otg_get_transceiver();
@@ -46,6 +52,12 @@ static int ux500_musb_init(struct musb *musb)
 	return 0;
 }
 
+/**
+ * ux500_musb_exit() - unregister the platform USB driver.
+ * @musb: struct musb pointer.
+ *
+ * This function unregisters the USB controller.
+ */
 static int ux500_musb_exit(struct musb *musb)
 {
 	otg_put_transceiver(musb->xceiv);
@@ -58,6 +70,13 @@ static const struct musb_platform_ops ux500_ops = {
 	.exit		= ux500_musb_exit,
 };
 
+/**
+ * ux500_probe() - Allocate the resources.
+ * @pdev: struct platform_device.
+ *
+ * This function allocates the required memory for the
+ * structures and initialize interrupts.
+ */
 static int __init ux500_probe(struct platform_device *pdev)
 {
 	struct musb_hdrc_platform_data	*pdata = pdev->dev.platform_data;
@@ -155,6 +174,13 @@ static int __exit ux500_remove(struct platform_device *pdev)
 }
 
 #ifdef CONFIG_PM
+/**
+ * ux500_suspend() - Handles the platform suspend.
+ * @dev: struct device
+ *
+ * This function gets triggered when the platform
+ * is going to suspend
+ */
 static int ux500_suspend(struct device *dev)
 {
 	struct ux500_glue	*glue = dev_get_drvdata(dev);
@@ -166,6 +192,13 @@ static int ux500_suspend(struct device *dev)
 	return 0;
 }
 
+/**
+ * ux500_resume() - Handles the platform resume.
+ * @dev: struct device
+ *
+ * This function gets triggered when the platform
+ * is going to resume
+ */
 static int ux500_resume(struct device *dev)
 {
 	struct ux500_glue	*glue = dev_get_drvdata(dev);
diff --git a/drivers/usb/musb/ux500_dma.c b/drivers/usb/musb/ux500_dma.c
index 75ed4ff3b7d..a9afca7af06 100644
--- a/drivers/usb/musb/ux500_dma.c
+++ b/drivers/usb/musb/ux500_dma.c
@@ -56,7 +56,13 @@ struct ux500_dma_controller {
 	dma_addr_t phy_base;
 };
 
-/* Work function invoked from DMA callback to handle tx transfers. */
+/**
+ * ux500_tx_work() - Invoked by worker thread
+ * @data: worker queue data
+ *
+ * This function is invoked by worker thread when the DMA transfer
+ * is completed in the transmit direction.
+*/
 static void ux500_tx_work(struct work_struct *data)
 {
 	struct ux500_dma_channel *ux500_channel = container_of(data,
@@ -75,7 +81,13 @@ static void ux500_tx_work(struct work_struct *data)
 	spin_unlock_irqrestore(&musb->lock, flags);
 }
 
-/* Work function invoked from DMA callback to handle rx transfers. */
+/**
+ * ux500_rx_work() - Invoked by worker thread
+ * @data: worker queue data
+ *
+ * This function is invoked by worker thread when the
+ * DMA transfer is completed in the receive direction.
+*/
 static void ux500_rx_work(struct work_struct *data)
 {
 	struct ux500_dma_channel *ux500_channel = container_of(data,
@@ -94,6 +106,12 @@ static void ux500_rx_work(struct work_struct *data)
 	spin_unlock_irqrestore(&musb->lock, flags);
 }
 
+/**
+ * ux500_dma_callback() - callback invoked when there is DMA data transfer
+ * @private_data:	pointer to DMA channel.
+ *
+ * This callback is invoked when the DMA tranfer is completed.
+*/
 void ux500_dma_callback(void *private_data)
 {
 	struct dma_channel *channel = (struct dma_channel *)private_data;
@@ -102,6 +120,18 @@ void ux500_dma_callback(void *private_data)
 	schedule_work(&ux500_channel->channel_work);
 }
 
+/**
+ * ux500_configure_channel() - configures the source, destination addresses and
+ *                       starts the transfer
+ * @channel:    pointer to DMA channel
+ * @packet_sz:  packet size
+ * @mode: Dma mode
+ * @dma_addr: DMA source address for transmit direction
+ *            or DMA destination address for receive direction
+ * @len: length
+ * This function configures the source and destination addresses for DMA
+ * operation and initiates the DMA transfer
+*/
 static bool ux500_configure_channel(struct dma_channel *channel,
 				u16 packet_sz, u8 mode,
 				dma_addr_t dma_addr, u32 len)
@@ -160,6 +190,15 @@ static bool ux500_configure_channel(struct dma_channel *channel,
 	return true;
 }
 
+/**
+ * ux500_dma_controller_allocate() - allocates the DMA channels
+ * @c: pointer to DMA controller
+ * @hw_ep: pointer to endpoint
+ * @is_tx: transmit or receive direction
+ *
+ * This function allocates the DMA channel and initializes
+ * the channel
+*/
 static struct dma_channel *ux500_dma_channel_allocate(struct dma_controller *c,
 				struct musb_hw_ep *hw_ep, u8 is_tx)
 {
@@ -197,7 +236,13 @@ static struct dma_channel *ux500_dma_channel_allocate(struct dma_controller *c,
 
 	return &(ux500_channel->channel);
 }
-
+/**
+ * ux500_dma_channel_release() - releases the DMA channel
+ * @channel:	channel to be released
+ *
+ * This function releases the DMA channel
+ *
+*/
 static void ux500_dma_channel_release(struct dma_channel *channel)
 {
 	struct ux500_dma_channel *ux500_channel = channel->private_data;
@@ -223,6 +268,16 @@ static int ux500_dma_is_compatible(struct dma_channel *channel,
 		return true;
 }
 
+/**
+ * ux500_dma_channel_program() - Configures the channel and initiates transfer
+ * @channel:	pointer to DMA channel
+ * @packet_sz:	packet size
+ * @mode: mode
+ * @dma_addr: physical address of memory
+ * @len: length
+ *
+ * This function configures the channel and initiates the DMA transfer
+*/
 static int ux500_dma_channel_program(struct dma_channel *channel,
 				u16 packet_sz, u8 mode,
 				dma_addr_t dma_addr, u32 len)
@@ -244,6 +299,12 @@ static int ux500_dma_channel_program(struct dma_channel *channel,
 	return ret;
 }
 
+/**
+ * ux500_dma_channel_abort() - aborts the DMA transfer
+ * @channel:	pointer to DMA channel.
+ *
+ * This function aborts the DMA transfer.
+*/
 static int ux500_dma_channel_abort(struct dma_channel *channel)
 {
 	struct ux500_dma_channel *ux500_channel = channel->private_data;
@@ -278,6 +339,12 @@ static int ux500_dma_channel_abort(struct dma_channel *channel)
 	return 0;
 }
 
+/**
+ * ux500_dma_controller_stop() - releases all the channels and frees the DMA pipes
+ * @c: pointer to DMA controller
+ *
+ * This function frees all of the logical channels and frees the DMA pipes
+*/
 static int ux500_dma_controller_stop(struct dma_controller *c)
 {
 	struct ux500_dma_controller *controller = container_of(c,
@@ -309,6 +376,15 @@ static int ux500_dma_controller_stop(struct dma_controller *c)
 	return 0;
 }
 
+
+/**
+ * ux500_dma_controller_start() - creates the logical channels pool and registers callbacks
+ * @c:	pointer to DMA Controller
+ *
+ * This function requests the logical channels from the DMA driver and creates
+ * logical channels based on event lines and also registers the callbacks which
+ * are invoked after data transfer in the transmit or receive direction.
+*/
 static int ux500_dma_controller_start(struct dma_controller *c)
 {
 	struct ux500_dma_controller *controller = container_of(c,
@@ -385,6 +461,12 @@ static int ux500_dma_controller_start(struct dma_controller *c)
 	return 0;
 }
 
+/**
+ * dma_controller_destroy() - deallocates the DMA controller
+ * @c:	pointer to dma controller.
+ *
+ * This function deallocates the DMA controller.
+*/
 void dma_controller_destroy(struct dma_controller *c)
 {
 	struct ux500_dma_controller *controller = container_of(c,
@@ -393,6 +475,15 @@ void dma_controller_destroy(struct dma_controller *c)
 	kfree(controller);
 }
 
+/**
+ * dma_controller_create() - creates the dma controller and initializes callbacks
+ *
+ * @musb:	pointer to mentor core driver data instance|
+ * @base:	base address of musb registers.
+ *
+ * This function creates the DMA controller and initializes the callbacks
+ * that are invoked from the Mentor IP core.
+*/
 struct dma_controller *__init
 dma_controller_create(struct musb *musb, void __iomem *base)
 {