ARM: PL08x: cleanup comments

 * this program; if not, write to the Free Software Foundation, Inc., 59

 * Temple Place - Suite 330, Boston, MA  02111-1307, USA.

 *

 * The full GNU General Public License is in this distribution in the

 * file called COPYING.

 * The full GNU General Public License is in this distribution in the file

 * called COPYING.

 *

 * Documentation: ARM DDI 0196G == PL080

 * Documentation: ARM DDI 0218E == PL081

 *

 * PL080 & PL081 both have 16 sets of DMA signals that can be routed to

 * any channel.

 * PL080 & PL081 both have 16 sets of DMA signals that can be routed to any

 * channel.

 *

 * The PL080 has 8 channels available for simultaneous use, and the PL081

 * has only two channels. So on these DMA controllers the number of channels

#define DRIVER_NAME	"pl08xdmac"

/**

 * struct vendor_data - vendor-specific config parameters

 * for PL08x derivatives

 * struct vendor_data - vendor-specific config parameters for PL08x derivatives

 * @channels: the number of channels available in this variant

 * @dualmaster: whether this version supports dual AHB masters

 * or not.

 * @dualmaster: whether this version supports dual AHB masters or not.

 */

struct vendor_data {

	u8 channels;

 *

 * Disabling individual channels could lose data.

 *

 * Disable the peripheral DMA after disabling the DMAC

 * in order to allow the DMAC FIFO to drain, and

 * hence allow the channel to show inactive

 *

 * Disable the peripheral DMA after disabling the DMAC in order to allow

 * the DMAC FIFO to drain, and hence allow the channel to show inactive

 */

static void pl08x_pause_phy_chan(struct pl08x_phy_chan *ch)

{

/*

 * Allocate a physical channel for a virtual channel

 *

 * Try to locate a physical channel to be used for this transfer. If all

 * are taken return NULL and the requester will have to cope by using

 * some fallback PIO mode or retrying later.

 */

static struct pl08x_phy_chan *

pl08x_get_phy_channel(struct pl08x_driver_data *pl08x,

	unsigned long flags;

	int i;

	/*

	 * Try to locate a physical channel to be used for

	 * this transfer. If all are taken return NULL and

	 * the requester will have to cope by using some fallback

	 * PIO mode or retrying later.

	 */

	for (i = 0; i < pl08x->vd->channels; i++) {

		ch = &pl08x->phy_chans[i];

};

/*

 * Autoselect a master bus to use for the transfer

 * this prefers the destination bus if both available

 * if fixed address on one bus the other will be chosen

 * Autoselect a master bus to use for the transfer this prefers the

 * destination bus if both available if fixed address on one bus the

 * other will be chosen

 */

static void pl08x_choose_master_bus(struct pl08x_lli_build_data *bd,

	struct pl08x_bus_data **mbus, struct pl08x_bus_data **sbus, u32 cctl)

}

/*

 * Fills in one LLI for a certain transfer descriptor

 * and advance the counter

 * Fills in one LLI for a certain transfer descriptor and advance the counter

 */

static void pl08x_fill_lli_for_desc(struct pl08x_lli_build_data *bd,

	int num_llis, int len, u32 cctl)

	 * Choose bus to align to

	 * - prefers destination bus if both available

	 * - if fixed address on one bus chooses other

	 * - modifies cctl to choose an appropriate master

	 */

	pl08x_choose_master_bus(&bd, &mbus, &sbus, cctl);

	if (txd->len < mbus->buswidth) {

		/*

		 * Less than a bus width available

		 * - send as single bytes

		 */

		/* Less than a bus width available - send as single bytes */

		while (bd.remainder) {

			dev_vdbg(&pl08x->adev->dev,

				 "%s single byte LLIs for a transfer of "

			total_bytes++;

		}

	} else {

		/*

		 *  Make one byte LLIs until master bus is aligned

		 *  - slave will then be aligned also

		 */

		/* Make one byte LLIs until master bus is aligned */

		while ((mbus->addr) % (mbus->buswidth)) {

			dev_vdbg(&pl08x->adev->dev,

				"%s adjustment lli for less than bus width "

			if (lli_len == target_len) {

				/*

				 * Can send what we wanted

				 */

				/*

				 * Can send what we wanted.

				 * Maintain alignment

				 */

				lli_len	= (lli_len/mbus->buswidth) *

			} else {

				/*

				 * So now we know how many bytes to transfer

				 * to get to the nearest boundary

				 * The next LLI will past the boundary

				 * - however we may be working to a boundary

				 *   on the slave bus

				 *   We need to ensure the master stays aligned

				 * to get to the nearest boundary.  The next

				 * LLI will past the boundary.  However, we

				 * may be working to a boundary on the slave

				 * bus.  We need to ensure the master stays

				 * aligned, and that we are working in

				 * multiples of the bus widths.

				 */

				odd_bytes = lli_len % mbus->buswidth;

				/*

				 * - and that we are working in multiples

				 *   of the bus widths

				 */

				lli_len -= odd_bytes;

			}

			if (odd_bytes) {

				/*

				 * Creep past the boundary,

				 * maintaining master alignment

				 * Creep past the boundary, maintaining

				 * master alignment

				 */

				int j;

				for (j = 0; (j < mbus->buswidth)

	}

	llis_va = txd->llis_va;

	/*

	 * The final LLI terminates the LLI.

	 */

	/* The final LLI terminates the LLI. */

	llis_va[num_llis - 1].lli = 0;

	/*

	 * The final LLI element shall also fire an interrupt

	 */

	/* The final LLI element shall also fire an interrupt. */

	llis_va[num_llis - 1].cctl |= PL080_CONTROL_TC_IRQ_EN;

#ifdef VERBOSE_DEBUG

			list_del(&txdi->node);

			pl08x_free_txd(pl08x, txdi);

		}

	}

}

}

/*

 * Code accessing dma_async_is_complete() in a tight loop

 * may give problems - could schedule where indicated.

 * If slaves are relying on interrupts to signal completion this

 * function must not be called with interrupts disabled

 * Code accessing dma_async_is_complete() in a tight loop may give problems.

 * If slaves are relying on interrupts to signal completion this function

 * must not be called with interrupts disabled.

 */

static enum dma_status

pl08x_dma_tx_status(struct dma_chan *chan,

		return ret;

	}

	/*

	 * schedule(); could be inserted here

	 */

	/*

	 * This cookie not complete yet

	 */

		}

	} else

		/*

		 * Else we're all set, paused and ready to roll,

		 * status will switch to PL08X_CHAN_RUNNING when

		 * we call issue_pending(). If there is something

		 * running on the channel already we don't change

		 * its state.

		 * Else we're all set, paused and ready to roll, status

		 * will switch to PL08X_CHAN_RUNNING when we call

		 * issue_pending(). If there is something running on the

		 * channel already we don't change its state.

		 */

		if (plchan->state == PL08X_CHAN_IDLE)

			plchan->state = PL08X_CHAN_PAUSED;

/*

 * Just check that the device is there and active

 * TODO: turn this bit on/off depending on the number of

 * physical channels actually used, if it is zero... well

 * shut it off. That will save some power. Cut the clock

 * at the same time.

 * TODO: turn this bit on/off depending on the number of physical channels

 * actually used, if it is zero... well shut it off. That will save some

 * power. Cut the clock at the same time.

 */

static void pl08x_ensure_on(struct pl08x_driver_data *pl08x)

{

	plchan->at = NULL;

	if (txd) {

		/*

		 * Update last completed

		 */

		/* Update last completed */

		plchan->lc = txd->tx.cookie;

	}

	/*

	 * If a new descriptor is queued, set it up

	 * plchan->at is NULL here

	 */

	/* If a new descriptor is queued, set it up plchan->at is NULL here */

	if (!list_empty(&plchan->pend_list)) {

		struct pl08x_txd *next;

		plchan->state = PL08X_CHAN_IDLE;

		/*

		 * And NOW before anyone else can grab that free:d

		 * up physical channel, see if there is some memcpy

		 * pending that seriously needs to start because of

		 * being stacked up while we were choking the

		 * physical channels with data.

		 * And NOW before anyone else can grab that free:d up

		 * physical channel, see if there is some memcpy pending

		 * that seriously needs to start because of being stacked

		 * up while we were choking the physical channels with data.

		 */

		list_for_each_entry(waiting, &pl08x->memcpy.channels,

				    chan.device_node) {

	val = readl(pl08x->base + PL080_ERR_STATUS);

	if (val) {

		/*

		 * An error interrupt (on one or more channels)

		 */

		/* An error interrupt (on one or more channels) */

		dev_err(&pl08x->adev->dev,

			"%s error interrupt, register value 0x%08x\n",

				__func__, val);

			mask |= (1 << i);

		}

	}

	/*

	 * Clear only the terminal interrupts on channels we processed

	 */

	/* Clear only the terminal interrupts on channels we processed */

	writel(mask, pl08x->base + PL080_TC_CLEAR);

	return mask ? IRQ_HANDLED : IRQ_NONE;

	int i;

	INIT_LIST_HEAD(&dmadev->channels);

	/*

	 * Register as many many memcpy as we have physical channels,

	 * we won't always be able to use all but the code will have

	/* Turn on the PL08x */

	pl08x_ensure_on(pl08x);

	/*

	 * Attach the interrupt handler

	 */

	/* Attach the interrupt handler */

	writel(0x000000FF, pl08x->base + PL080_ERR_CLEAR);

	writel(0x000000FF, pl08x->base + PL080_TC_CLEAR);

 *

 * Please credit ARM.com

 * Documentation: ARM DDI 0196D

 *

 */

#ifndef AMBA_PL08X_H

 * @circular_buffer: whether the buffer passed in is circular and

 * shall simply be looped round round (like a record baby round

 * round round round)

 * @single: the device connected to this channel will request single

 * DMA transfers, not bursts. (Bursts are default.)

 * @single: the device connected to this channel will request single DMA

 * transfers, not bursts. (Bursts are default.)

 * @periph_buses: the device connected to this channel is accessible via

 * these buses (use PL08X_AHB1 | PL08X_AHB2).

 */

 * @addr: current address

 * @maxwidth: the maximum width of a transfer on this bus

 * @buswidth: the width of this bus in bytes: 1, 2 or 4

 * @fill_bytes: bytes required to fill to the next bus memory

 * boundary

 * @fill_bytes: bytes required to fill to the next bus memory boundary

 */

struct pl08x_bus_data {

	dma_addr_t addr;

 * struct pl08x_phy_chan - holder for the physical channels

 * @id: physical index to this channel

 * @lock: a lock to use when altering an instance of this struct

 * @signal: the physical signal (aka channel) serving this

 * physical channel right now

 * @serving: the virtual channel currently being served by this

 * physical channel

 * @signal: the physical signal (aka channel) serving this physical channel

 * right now

 * @serving: the virtual channel currently being served by this physical

 * channel

 */

struct pl08x_phy_chan {

	unsigned int id;

	size_t len;

	dma_addr_t llis_bus;

	struct pl08x_lli *llis_va;

	bool active;

	/* Default cctl value for LLIs */

	u32 cctl;

	/*

};

/**

 * struct pl08x_dma_chan_state - holds the PL08x specific virtual

 * channel states

 * struct pl08x_dma_chan_state - holds the PL08x specific virtual channel

 * states

 * @PL08X_CHAN_IDLE: the channel is idle

 * @PL08X_CHAN_RUNNING: the channel has allocated a physical transport

 * channel and is running a transfer on it

 * @host: a pointer to the host (internal use)

 * @state: whether the channel is idle, paused, running etc

 * @slave: whether this channel is a device (slave) or for memcpy

 * @waiting: a TX descriptor on this channel which is waiting for

 * a physical channel to become available

 * @waiting: a TX descriptor on this channel which is waiting for a physical

 * channel to become available

 */

struct pl08x_dma_chan {

	struct dma_chan chan;

};

/**

 * struct pl08x_platform_data - the platform configuration for the

 * PL08x PrimeCells.

 * struct pl08x_platform_data - the platform configuration for the PL08x

 * PrimeCells.

 * @slave_channels: the channels defined for the different devices on the

 * platform, all inclusive, including multiplexed channels. The available

 * physical channels will be multiplexed around these signals as they

 * are requested, just enumerate all possible channels.

 * @get_signal: request a physical signal to be used for a DMA

 * transfer immediately: if there is some multiplexing or similar blocking

 * the use of the channel the transfer can be denied by returning

 * less than zero, else it returns the allocated signal number

 * physical channels will be multiplexed around these signals as they are

 * requested, just enumerate all possible channels.

 * @get_signal: request a physical signal to be used for a DMA transfer

 * immediately: if there is some multiplexing or similar blocking the use

 * of the channel the transfer can be denied by returning less than zero,

 * else it returns the allocated signal number

 * @put_signal: indicate to the platform that this physical signal is not

 * running any DMA transfer and multiplexing can be recycled

 * @lli_buses: buses which LLIs can be fetched from: PL08X_AHB1 | PL08X_AHB2