From b7afc6b9c4177c64b68c0395428d0ff5b02562d1 Mon Sep 17 00:00:00 2001 From: Sakethram Bommisetti Date: Mon, 29 Aug 2011 12:29:44 +0530 Subject: USB:Updating the documentation Documentation from usb. Signed-off-by: Sakethram Bommisetti Conflicts: Documentation/DocBook/Makefile --- drivers/usb/musb/ux500_dma.c | 97 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 3 deletions(-) (limited to 'drivers/usb/musb/ux500_dma.c') 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) { -- cgit v1.2.3