USB:Updating the documentation

Documentation from usb.

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

Conflicts:

	Documentation/DocBook/Makefile

2 files changed, 127 insertions, 3 deletions

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)
 {