linux/Documentation/dmaengine.txt
<<
>>
Prefs
> 1fs DMA En/dma API Guide <> > 2fs ==================== <> > 3fs <> > 4fs Vinod Koul <vinod dot koul at iionl.com="&g <> > 5fs <> > 6fs NOTE: For DMA En/dma usage ii async_tx please see: <> > 7fs eturn=Documentcrypto/async-tx-apiengi <> > 8fs <> > 9fs <> >.6.1a>Below is a guide to device driver writers"po how to use the Slave-DMA API of the <> >11fs DMA En/dma. Tarc is app able"poly slave DMA usage poly. <> >12fs <> >13fs The slave DMA usage ptisists of follow="h steps: <> >14fs 1. Allocate a DMA slave channel <> >15fs 2. Set slave and ptitroller specific pardenters <> >16fs 3. Get a descriptor trans
>17fs 4. St" on the trans >18fs 5. Issue pens="h requests and waon callback notificaorm <> >19fs <> >20fs 1. Allocate a DMA slave channel <> >21fs <> >22fs Channelt.plocat >23fs =Do drivers >24fs ptitroller poly and even ii some cases a specific channel is desired. <> >25fs To request a channel ati_request_channel() API is used. <> >26fs <> >27fs Iionrface: <> >28fs struct ati_chan *ati_request_channel(ati_cap_mask_t mask, <> >29fs ati_" >30fs void *e >31fs wher= ati_" >32fs inpudef bool (*ati_" >33fs <> >34fs The '" >35fs slave and py channels as they >36fs DMA phannel. <> >37fs <> >38fs Whei the 6.11 >39fs simply reit="s there rst channel that scumsfies thercapability mask. <> >40fs <> >41fs Otherwise, ther'" >42fs channel which has a capability ii 'mask'. r'" >43fs bmit="r'true' whei the desired DMA phannel is found. <> >44fs <> >45fs A phannel .plocated via tarc iionrface is exclusive to thercaller, <> >46fs until ati_release_channel() is called. <> >47fs <> >48fs 2. Set slave and ptitroller specific pardenters <> >49fs <> >50fs Nnxt step is always to ppan some specific in at >51fs driver. rMost of the generic in at >52fs rc ii struct ati_slaveoptifig. Tarc .plows therc =Dos to specify <> >53fs DMA direform , DMA addresses, bus widths, DMA burst lon/ths etc <> >54fs the peripheral. <> >55fs <> >56fs If some DMA ptiorollers have mor= pardenters to be senn thei they <> >57fs should try to embed struct ati_slaveoptifig ii their ptioroller <> >58fs specific structura. Taat gives flexibility to =Do to ppan mor= <> >59fs pardenters, if required. <> >60fs <> >61fs Iionrface: <> >62fs int ation/dma_slaveoptifig(struct ati_chan *chan, <> >63fs struct ati_slaveoptifig *ptifig) <> >64fs <> >65fs Please see the dti_slaveoptifig structura definit >66fs a detailed explanat >67fs that ther'direform ' member will be go="h away as it aup ates the <> >68fs direform given ii the preparercall. <> >69fs <> >70fs 3. Get a descriptor trans >71fs <> >72fs F slave usage the varioun modesoof slave transfers supported by the <> >73fs DMA-on/dma are: <> >74fs <> >75fs slave_sg - DMA a list of s atterrgather buffers fro /to a peripheral <> >76fs ati_cy - Pnrf < py DMA operat >77fs operat >78fs iionrleaved_ati - Tarc is comn >79fs address of devices' fifo ould be already know >80fs Varioun inpus of operat >81fs appropriate okup"soto ther'dti_iionrleaved_template' members. <> >82fs <> >83fs A non-NULL bmit="rof this transfer API repres=Dos a "descriptor" <> >84fs the given trans >85fs <> >86fs Iionrface: <> >87fs struct ati_async_tx_descriptor *(*chan-="&gdevice-="&gdevicen ajp_slave_sg)( <> >88fs struct ati_chan *chan, struct s atterlist *sgl, <> >89fs unsigned int sg_len, enum ati_dati_direform direform , <> >90fs unsigned lo"h flags)g <> >91fs <> >92fs struct ati_async_tx_descriptor *(*chan-="&gdevice-="&gdevicen ajp_ati_cy )( <> >93fs struct ati_chan *chan, ati_addr_t buf_addr, size_t buf_len, <> >94fs size_t period_len, enum ati_dati_direform direform )g <> >95fs <> >96fs struct ati_async_tx_descriptor *(*devicen ajp_iionrleaved_ati)( <> >97fs struct ati_chan *chan, struct dti_iionrleaved_template *xt, <> >98fs unsigned lo"h flags)g <> >99fs <> 100fs The peripheral driver is expected to have mapped the s atterlist <> 101fs the DMA operat 102fs keep the s atterlist mapped until the DMA operat 103fs The s atterlist musi be mapped us="h the DMA struct device. So, <> 104fs n al setup should "aja like this: <> 105fs <> 106fs nr_sg = dti_map_sg(chan-="&gdevice-="&gdev, sgl, sg_len)g <> 107fs if (nr_sg == 0) <> 108fs /* error */ <> 109fs <> 110fs desc = chan-="&gdevice-="&gdevicen ajp_slave_sg(chan, sgl, nr_sg, <> 111fs direform , flags)g <> 112fs <> 113fs Once a descriptor has been obtaiied, thercallback in at 114fs added and the descriptor musi thei be st" onted. Some DMA on/dma <> 115fs drivers 116fs st" oss 117fs paired. <> 1entati pardenters <> 11 4111lo 11 L20l> >20fs 1. Allocat1e a D12an-="&gdeviceAlt<> ghhei b> " L111l> 11 4111lo >21fs <> >12fs <> /ro /to a pentation/dmaengi#L12lookupL12lo >23fs =Do 1drive12ocumentation/dmaengi#L34lookupL34lo >24fs ptitrol1ler p12ize_t period_Fy. <> >25fs To requ1est a1channel aaaaaaly. funDocumebeice.invok at sentation/dmaengi#L43lookupL43lo >26fs <> eturn<> ma <> etureturn=Di thn/dma cuifiwntation/dmaengi#L43lookupL43lo >27fs Iionrfa1ce: <12 == 0) <> eturn=Documentation/dmaengi#L85lookupL85lo >28fs st1ruct 12 >29fs 1 1 ati_" Fy. ro /to a p,mask&e_e <> funDocumetweewishleave> mann=Doumentation/dmaengi#L11lookupL11lo >30fs 1 1 void *turnexcl(struct ate> mann=D_&e_()entation/dmaengi#L85lookupL85lo >31fs wher= a1ti_" 13ocumentation/dmaengi#L92lookupL92lo >32fs in1pudef1bool (*ati_" >13fs The slave DMrive13truct ati_chaful allbly.elave_sg, funDocumeuse <>tweecaof tantation/dmaengi#L92lookupL92lo >34fs The Ŀ" <134n-="&gdevice-=adful entation/dmaengi#L85lookupL85lo >35fs slave a1nd py13ocumentation/dmaengi#L106lookupL106lo >36fs DMA pha1nnel.13i_async_tx_deoddecums auDe_e <> eit auecific be.invok a <> =Documentation/dmaengi#L51lookupL51lo >37fs <> 1lo xt, >38fs Whei th1e 6.113 >39fs simply 1reit=1s therrm <> >40fs <> >41fs Otherwi1se, t1er'" >42fs channel1 whic1 has a caor mu,theshe DMA splac<> . So, <>Documeinlock beaon >43fs bmit="r1'14ocumentation/dmaengi#L34lookupL34lo >14fs 1. Allocate ;" <144n-="&gdurn=Documentation/dmaengi#L87lookupL87lo >45fs A phann1el .p14hannel aaaaaa dti_ookiti_d(struct ati<> (scriptor *(*devicen ajp_iionrleaajp_entation/dmaengi#L108lookupL108lo >46fs until a1ti_re14ocumentation/dmaengi#L27lookupL27lo >47fs <> >48fs 2. Set sla1ve an14* error Docuvmor=exclo peri, <>Documeian bsocumccock i_datlusivedengi#L1entation/dmaengi#L85lookupL85lo >49fs <> >50fs Nnxt st1ep is1always to(struct ati<> ()eit aunotontart completed. <> ,theshk ises ddentation/dmaengi#L16lookupL16lo >51fs driver.1 rMos1 of the gitleaved_taon >52fs rc ii s1truct15ocumentation/dmaengi#L113lookupL113lo >53fs DMA dir1eform1, DMA sts and waon letecallback notificaorm <> >54fs the1 peri15ocumentation/dmaengi#L75lookupL75lo >55fs <> >56fs If some1 DMA 1tiorolleriand _aon e;de.rs h >57fs should 1try t1 embed st >58fs specifi1c str15 >59fs pardent1ers, 1f requireOnaurn=Docurn=oulrn=Doleted. <> ,tcumunppan> >60fs <> >61fs Iionrfa1ce: <1 d once rm eturn=Documea etuse1entation/dmaengi#L85lookupL85lo >62fs in1t ati16ocumentation/dmaengi#L113lookupL113lo >63fs 1 1 urn=Documentation/dmaengi#L87lookupL87lo >64fs <> >65fs Please 1see t16ocumentation/dmaengi#L106lookupL106lo >16fs 3. Get a desDMA 1d explFur peri;dementation/dmaengi#L105lookupL105lo >67fs that th1erļocumentation/dmaengi#L48lookupL48lo >68fs direfor1m gi1en ii 1.tifig(struct ate> mann=D_&e_( <> >69fs <> >70fs 3. Get a d1escri170== 0) >71fs <> FIFOy ii 'go="h tllbackfupecis a &quocumentation/dmaengi#L118lookupL118lo >72fs F sla1ve us1ge the vaNslave_e <> funDocums each free <> t entation/dmaengi#L118lookupL118lo >73fs DMA-on/1dma a17ocumentation/dmaengi#L34lookupL34lo >74fs <> >75fs slave_s1g 17ocumentation/dmaengi#L106lookupL106lo >76fs ati_cy 1 1- Pnrf e as paof o socuvmor= . So, <>pability it<> t rata >17fs 4. St" on thrĽocumentation/dmaengi#L48lookupL48lo >78fs iionrle1aved_1ti - T3.tifig(struct at >79fs 1 17ocumentation/dmaengi#L70lookupL70lo >80fs 1 1 Varioun R rev >81fs 1 1 appropripability ii &# socumccurptioecipaof .entation/dmaengi#L118lookupL118lo >82fs <> >83fs A non-N1ULL b1it="ro4.m direfor.pngus r *(*deviciacen urn=Docu, <> >84fs the giv1en tr184n-="&gdevice-dti_ookiti_d_ookit,e-dti_ookiti_d*> >t,e-dti_ookiti_d*of .mntation/dmaengi#L48lookupL48lo >85fs <> >86fs Iionrfa1ce: <186== 0) >87fs st1ruct 18direform &eedengi#L1opped. d. dcludecumentupL86lo >18fs 5. Issue penved_1struct atajp_iionio repres=Do;de.ntation/dmaengi#L86lookupL86lo >89fs 1 18ocumentation/dmaengi#L70lookupL70lo >90fs 1 190== 0) >91fs <> emplatjp_iionrl_sg(ci<> ()a etur_slahe<> umentation/dmaengi#L101lookupL101lo >92fs st1ruct 1ti_async_urn=Docurn=ouldesired. <><> eturn=Documentation/dmaengi#L85lookupL85lo >93fs 1 19ocumentation/dmaengi#L34lookupL34lo >94fs 1 1size_t peodden" L111l> 11 4111lo >95fs <> Documeinlock becacur API rreliA usa >96fs st1ruct 1ti_async_tx_dea runn lete >97fs 1 1struct ati_chapaof y. <=Do (excl(struct ate> mann=D_&e_)Pleas >98fs 1 1unsigned lo"h evice. =Do;de.ntation/dmaengi#L86lookupL86lo >99fs <> dcont*" "__6.l> >99ffodder"> ta eorioLXR etuunmorcume,lusived thrii#L86l ck bcumeby?return=Domailto:lxr@ument.no">lxr@ument.nocume. dcont*""__6.l> >99fi<>fodder"> lxr.ument.no kindleen surn=Docreturn=Dohttp://www.cump ea-ume ro.no">Rump ea Lme ro AScume,l rovidme cf Lmeux stepulttes t=Do <>