0001 ==============================
0002 PXA/MMP - DMA Slave controller
0003 ==============================
0004
0005 Constraints
0006 ===========
0007
0008 a) Transfers hot queuing
0009 A driver submitting a transfer and issuing it should be granted the transfer
0010 is queued even on a running DMA channel.
0011 This implies that the queuing doesn't wait for the previous transfer end,
0012 and that the descriptor chaining is not only done in the irq/tasklet code
0013 triggered by the end of the transfer.
0014 A transfer which is submitted and issued on a phy doesn't wait for a phy to
0015 stop and restart, but is submitted on a "running channel". The other
0016 drivers, especially mmp_pdma waited for the phy to stop before relaunching
0017 a new transfer.
0018
0019 b) All transfers having asked for confirmation should be signaled
0020 Any issued transfer with DMA_PREP_INTERRUPT should trigger a callback call.
0021 This implies that even if an irq/tasklet is triggered by end of tx1, but
0022 at the time of irq/dma tx2 is already finished, tx1->complete() and
0023 tx2->complete() should be called.
0024
0025 c) Channel running state
0026 A driver should be able to query if a channel is running or not. For the
0027 multimedia case, such as video capture, if a transfer is submitted and then
0028 a check of the DMA channel reports a "stopped channel", the transfer should
0029 not be issued until the next "start of frame interrupt", hence the need to
0030 know if a channel is in running or stopped state.
0031
0032 d) Bandwidth guarantee
0033 The PXA architecture has 4 levels of DMAs priorities : high, normal, low.
0034 The high priorities get twice as much bandwidth as the normal, which get twice
0035 as much as the low priorities.
0036 A driver should be able to request a priority, especially the real-time
0037 ones such as pxa_camera with (big) throughputs.
0038
0039 Design
0040 ======
0041 a) Virtual channels
0042 Same concept as in sa11x0 driver, ie. a driver was assigned a "virtual
0043 channel" linked to the requestor line, and the physical DMA channel is
0044 assigned on the fly when the transfer is issued.
0045
0046 b) Transfer anatomy for a scatter-gather transfer
0047
0048 ::
0049
0050 +------------+-----+---------------+----------------+-----------------+
0051 | desc-sg[0] | ... | desc-sg[last] | status updater | finisher/linker |
0052 +------------+-----+---------------+----------------+-----------------+
0053
0054 This structure is pointed by dma->sg_cpu.
0055 The descriptors are used as follows :
0056
0057 - desc-sg[i]: i-th descriptor, transferring the i-th sg
0058 element to the video buffer scatter gather
0059
0060 - status updater
0061 Transfers a single u32 to a well known dma coherent memory to leave
0062 a trace that this transfer is done. The "well known" is unique per
0063 physical channel, meaning that a read of this value will tell which
0064 is the last finished transfer at that point in time.
0065
0066 - finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN
0067
0068 - linker: has ddadr= desc-sg[0] of next transfer, dcmd=0
0069
0070 c) Transfers hot-chaining
0071 Suppose the running chain is:
0072
0073 ::
0074
0075 Buffer 1 Buffer 2
0076 +---------+----+---+ +----+----+----+---+
0077 | d0 | .. | dN | l | | d0 | .. | dN | f |
0078 +---------+----+-|-+ ^----+----+----+---+
0079 | |
0080 +----+
0081
0082 After a call to dmaengine_submit(b3), the chain will look like:
0083
0084 ::
0085
0086 Buffer 1 Buffer 2 Buffer 3
0087 +---------+----+---+ +----+----+----+---+ +----+----+----+---+
0088 | d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f |
0089 +---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+
0090 | | | |
0091 +----+ +----+
0092 new_link
0093
0094 If while new_link was created the DMA channel stopped, it is _not_
0095 restarted. Hot-chaining doesn't break the assumption that
0096 dma_async_issue_pending() is to be used to ensure the transfer is actually started.
0097
0098 One exception to this rule :
0099
0100 - if Buffer1 and Buffer2 had all their addresses 8 bytes aligned
0101
0102 - and if Buffer3 has at least one address not 4 bytes aligned
0103
0104 - then hot-chaining cannot happen, as the channel must be stopped, the
0105 "align bit" must be set, and the channel restarted As a consequence,
0106 such a transfer tx_submit() will be queued on the submitted queue, and
0107 this specific case if the DMA is already running in aligned mode.
0108
0109 d) Transfers completion updater
0110 Each time a transfer is completed on a channel, an interrupt might be
0111 generated or not, up to the client's request. But in each case, the last
0112 descriptor of a transfer, the "status updater", will write the latest
0113 transfer being completed into the physical channel's completion mark.
0114
0115 This will speed up residue calculation, for large transfers such as video
0116 buffers which hold around 6k descriptors or more. This also allows without
0117 any lock to find out what is the latest completed transfer in a running
0118 DMA chain.
0119
0120 e) Transfers completion, irq and tasklet
0121 When a transfer flagged as "DMA_PREP_INTERRUPT" is finished, the dma irq
0122 is raised. Upon this interrupt, a tasklet is scheduled for the physical
0123 channel.
0124
0125 The tasklet is responsible for :
0126
0127 - reading the physical channel last updater mark
0128
0129 - calling all the transfer callbacks of finished transfers, based on
0130 that mark, and each transfer flags.
0131
0132 If a transfer is completed while this handling is done, a dma irq will
0133 be raised, and the tasklet will be scheduled once again, having a new
0134 updater mark.
0135
0136 f) Residue
0137 Residue granularity will be descriptor based. The issued but not completed
0138 transfers will be scanned for all of their descriptors against the
0139 currently running descriptor.
0140
0141 g) Most complicated case of driver's tx queues
0142 The most tricky situation is when :
0143
0144 - there are not "acked" transfers (tx0)
0145
0146 - a driver submitted an aligned tx1, not chained
0147
0148 - a driver submitted an aligned tx2 => tx2 is cold chained to tx1
0149
0150 - a driver issued tx1+tx2 => channel is running in aligned mode
0151
0152 - a driver submitted an aligned tx3 => tx3 is hot-chained
0153
0154 - a driver submitted an unaligned tx4 => tx4 is put in submitted queue,
0155 not chained
0156
0157 - a driver issued tx4 => tx4 is put in issued queue, not chained
0158
0159 - a driver submitted an aligned tx5 => tx5 is put in submitted queue, not
0160 chained
0161
0162 - a driver submitted an aligned tx6 => tx6 is put in submitted queue,
0163 cold chained to tx5
0164
0165 This translates into (after tx4 is issued) :
0166
0167 - issued queue
0168
0169 ::
0170
0171 +-----+ +-----+ +-----+ +-----+
0172 | tx1 | | tx2 | | tx3 | | tx4 |
0173 +---|-+ ^---|-+ ^-----+ +-----+
0174 | | | |
0175 +---+ +---+
0176 - submitted queue
0177 +-----+ +-----+
0178 | tx5 | | tx6 |
0179 +---|-+ ^-----+
0180 | |
0181 +---+
0182
0183 - completed queue : empty
0184
0185 - allocated queue : tx0
0186
0187 It should be noted that after tx3 is completed, the channel is stopped, and
0188 restarted in "unaligned mode" to handle tx4.
0189
0190 Author: Robert Jarzmik <robert.jarzmik@free.fr>
