<?xml version="1.0" encoding="utf-8"?>+
−
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->+
−
<!-- This component and the accompanying materials are made available under the terms of the License +
−
"Eclipse Public License v1.0" which accompanies this distribution, +
−
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->+
−
<!-- Initial Contributors:+
−
    Nokia Corporation - initial contribution.+
−
Contributors: +
−
-->+
−
<!DOCTYPE concept+
−
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">+
−
<concept id="GUID-A4C19890-2380-5498-A5F8-3B6D95CEFEF4" xml:lang="en"><title>PSL+
−
Implementation</title><shortdesc>Describes how to create the PSL implementation.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>+
−
<p>To create a port of the DMA Framework, you must create an implementation+
−
of the PSL for the DMA controller hardware.</p>+
−
<section id="GUID-8664FA8F-E53A-5DBA-999F-A0B800C1F54B"><title>Define and+
−
implement PSL-specific channel classes</title> <p>The choice of class to be+
−
used for implementing DMA channels is governed by the mode of operation to+
−
be supported: </p> <ul>+
−
<li id="GUID-C254C7CA-D010-5885-811D-05BEAF068EDD"><p>single-buffer channels+
−
should use <xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref>  </p> </li>+
−
<li id="GUID-91DDE5AD-16E5-5FCE-86E9-80069F2CCDDB"><p>double-buffer channels+
−
should use <xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel</apiname></xref>  </p> </li>+
−
<li id="GUID-994E863D-2C32-5AE3-931A-B852855883CA"><p>scatter-gather channels+
−
should use <xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref>  </p> </li>+
−
</ul> <p>These three classes are defined in <filepath>dma.h</filepath>. </p> <p>In+
−
addition, the PSL may need to store channel-specific data. One way of achieving+
−
this is by deriving a PSL-specific class from one of the generic ones. For+
−
example, the template scatter-gather implementation defines a <codeph>TTemplateSgChannel</codeph> class+
−
derived from <codeph>TDmaSgChannel</codeph> for storing data when appending+
−
new descriptors to a running channel: </p> <codeblock id="GUID-C4807321-01A3-5893-800A-6E22B8B5E131" xml:space="preserve">class TTemplateSgChannel : public TDmaSgChannel+
−
    {+
−
public:+
−
    TDmaDesc* iTmpDes;+
−
    TPhysAddr iTmpDesPhysAddr;+
−
    };+
−
+
−
      </codeblock> </section>+
−
<section id="GUID-0991CFB7-B37E-57B9-BC1F-4A69FEDAF5A5"><title>Define and+
−
implement the controller classes</title> <p>A controller can either be a physical+
−
controller, or a logical one depending on which <xref href="GUID-97F97D7B-D5A3-5471-A359-77B805ED198C.dita">DMA+
−
mode you intend to support</xref>. </p> <p>The PSL (platform-specific layer)+
−
must define one concrete controller class per supported controller. A controller+
−
class is derived from <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref>. The concrete class must implement+
−
all the pure virtual functions defined in <codeph>TDmac</codeph>, and, optionally+
−
the functions used to manipulate hardware descriptors. </p> <p>Taking the+
−
template port as an example, the class is defined as: </p> <codeblock id="GUID-1C275111-6597-5616-822A-9EABF40BFE77" xml:space="preserve">class TTemplateDmac : public TDmac+
−
    {+
−
public:+
−
    TTemplateDmac();+
−
    TInt Create();+
−
private:+
−
    // from TDmac (PIL pure virtual)+
−
    virtual void Transfer(const TDmaChannel&amp; aChannel, const SDmaDesHdr&amp; aHdr);+
−
    virtual void StopTransfer(const TDmaChannel&amp; aChannel);+
−
    virtual TBool IsIdle(const TDmaChannel&amp; aChannel);+
−
    virtual TInt MaxTransferSize(TDmaChannel&amp; aChannel, TUint aFlags, TUint32 aPslInfo);+
−
    virtual TUint MemAlignMask(TDmaChannel&amp; aChannel, TUint aFlags, TUint32 aPslInfo);+
−
    // from TDmac (PIL virtual)+
−
    virtual void InitHwDes(const SDmaDesHdr&amp; aHdr, TUint32 aSrc, TUint32 aDest, TInt aCount,+
−
                            TUint aFlags, TUint32 aPslInfo, TUint32 aCookie);+
−
    virtual void ChainHwDes(const SDmaDesHdr&amp; aHdr, const SDmaDesHdr&amp; aNextHdr);+
−
    virtual void AppendHwDes(const TDmaChannel&amp; aChannel, const SDmaDesHdr&amp; aLastHdr,+
−
                             const SDmaDesHdr&amp; aNewHdr);+
−
    virtual void UnlinkHwDes(const TDmaChannel&amp; aChannel, SDmaDesHdr&amp; aHdr);+
−
    // other+
−
    static void Isr(TAny* aThis);+
−
    inline TDmaDesc* HdrToHwDes(const SDmaDesHdr&amp; aHdr);+
−
private:+
−
    static const SCreateInfo KInfo;+
−
public:+
−
    TTemplateSgChannel iChannels[KChannelCount];+
−
    };+
−
</codeblock> <p>Notes: </p> <ul>+
−
<li id="GUID-4E8059FF-0BBC-5F65-9F66-3C96BC86FE55"><p>The array of channels+
−
must be defined in the PSL controller class because only the PSL knows what+
−
kind of channels are used. </p> </li>+
−
<li id="GUID-66E7787B-E933-5E17-9169-E0D245B9D27A"><p>The PSL controller class+
−
must be allocated in the BSS section of the DMA kernel extension. The second+
−
phase constructor must be called from the extension entry point. </p> </li>+
−
<li id="GUID-7306F4CB-5D0F-5E82-AC61-E068A48C9C9B"><p>The C++ constructor+
−
must pass a <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-BBD2153C-4B41-357C-9299-D710930AFCBE"><apiname>TDmac::SCreateInfo</apiname></xref> structure to the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> constructor.+
−
This structure defines what the PIL (platform-independent layer) needs to+
−
know about the underlying DMA controller. The template <codeph>TTemplateDmac</codeph> constructor+
−
just passes a <codeph>TDmac::ScreateInfo</codeph> structure, which defines+
−
the layout of the (base class managed) descriptor pool to the base class constructor+
−
through a ctor list: </p> <codeblock id="GUID-E00DD5C0-0976-58A0-B3C0-22DFD9216BC0" xml:space="preserve">TTemplateDmac::TTemplateDmac()+
−
//+
−
// Constructor.+
−
//+
−
    : TDmac(KInfo)+
−
    {}+
−
+
−
          </codeblock> <p>where KInfo is a <codeph>TDmac::ScreateInfo</codeph> type. </p> </li>+
−
<li id="GUID-4C6FB95D-BE6F-5938-8AC3-824B3BB508EE"><p>The PSL controller class+
−
needs a second phase constructor. This is the <codeph>Create()</codeph> function,+
−
which must: </p> <ol id="GUID-33DC912F-C5B4-5F33-A427-62700522D958">+
−
<li id="GUID-F0E8A497-B09F-5DA0-A94A-3B08FC28707C"><p>call the second phase+
−
constructor of the base class: <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-9B0C8C35-F149-3358-90B8-B4670CFE888F"><apiname>TDmac::Create()</apiname></xref>. </p> </li>+
−
<li id="GUID-1FD43FAD-4F43-557E-9EF0-19C725DD5FF5"><p>perform any hardware-specific+
−
initialisation. </p> </li>+
−
<li id="GUID-A522B8D4-744B-5C5B-B684-C82F34462171"><p>bind and enable the+
−
DMA interrupt(s). </p> </li>+
−
</ol> <p>In the template port, <codeph>Create()</codeph> calls the base class <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-9B0C8C35-F149-3358-90B8-B4670CFE888F"><apiname>TDmac::Create()</apiname></xref> function+
−
and then initialises the template specific channel object members (the temporary+
−
descriptor fields used for appending requests to live channels), and performs+
−
platform specific initialisation for the interrupt dispatch of DMA interrupt+
−
events: </p> <codeblock id="GUID-FBCC8132-129C-53A4-99B7-290B56C3035D" xml:space="preserve">TInt TTemplateDmac::Create()+
−
//+
−
// Second phase construction.+
−
//+
−
    {+
−
    TInt r = TDmac::Create(KInfo);                            // Base class Create()+
−
    if (r == KErrNone)+
−
        {+
−
        __DMA_ASSERTA(ReserveSetOfDes(KChannelCount) == KErrNone);+
−
        for (TInt i=0; i &lt; KChannelCount; ++i)+
−
            {+
−
            TDmaDesc* pD = HdrToHwDes(*iFreeHdr);+
−
            iChannels[i].iTmpDes = pD;+
−
            iChannels[i].iTmpDesPhysAddr = DesLinToPhys(pD);+
−
            iFreeHdr = iFreeHdr-&gt;iNext;+
−
            }+
−
        r = Interrupt::Bind(EAsspIntIdDma, Isr, this);+
−
        if (r == KErrNone)+
−
            {+
−
            // TO DO: Map DMA clients (requests) to DMA channels here.+
−
+
−
            r = Interrupt::Enable(EAsspIntIdDma);+
−
            }+
−
        }+
−
    return r;+
−
    }+
−
          </codeblock> </li>+
−
</ul> </section>+
−
<section id="GUID-0DBA2E68-7759-5447-B34B-14F237369CB1"><title>Implement the+
−
channel allocator</title> <p>Channel allocation is implemented in the PSL+
−
(platform-specific layer) because this is a hardware-specific operation. There+
−
are two basic options: </p> <ul>+
−
<li id="GUID-A9246754-F21B-5BFC-9FDB-2CE5C92D1FA3"><p>Preallocate, at design+
−
time, one channel per DMA-aware peripheral. This is the simplest approach,+
−
and it should be acceptable for most Symbian platform devices because the+
−
set of supported peripherals is closed. In this case, cookies passed by client+
−
device drivers map uniquely to DMA channels. </p> </li>+
−
<li id="GUID-C1164FA0-9B70-55C1-9C5A-2D02728FA67A"><p>Full dynamic allocation.+
−
This is a simple approach too, but DMA channels are, in general, not completely+
−
identical. For example, some channels may have greater priorities than others. </p> </li>+
−
</ul> <p>Mixed schemes are also possible, for example, client device driver+
−
cookies could be used to select a subset of channels, and dynamic allocation+
−
used inside this subset. </p> <p>Whatever option is chosen, the PSL must provide+
−
an implementation for the function <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-934F46B3-1DF9-3870-87EE-A8E2DEF82810"><apiname>DmaChannelMgr::Open()</apiname></xref>.+
−
The template implementation is: </p> <codeblock id="GUID-9C7F5850-F72B-5A16-9DA0-606FBABAB5F0" xml:space="preserve">TDmaChannel* DmaChannelMgr::Open(TUint32 aOpenId)+
−
//+
−
//+
−
//+
−
    {+
−
    __KTRACE_OPT(KDMA, Kern::Printf("&gt;DmaChannelMgr::Open aOpenId=%d", aOpenId));+
−
+
−
    __DMA_ASSERTA(aOpenId &lt; static_cast&lt;TUint32&gt;(KChannelCount));+
−
+
−
    TDmaChannel* pC = Controller.iChannels + aOpenId;+
−
    if (pC-&gt;IsOpened())+
−
        pC = NULL;+
−
    else+
−
        {+
−
        pC-&gt;iController = &amp;Controller;+
−
        pC-&gt;iPslId = aOpenId;+
−
        }+
−
+
−
    return pC;+
−
    }+
−
      </codeblock> <p>The template DMA channel manager returns a pointer to+
−
a DMA channel if the channel has not been previously allocated. Note that+
−
since channels possess preset priorities, the device drivers must be aware+
−
of which channel(s) they require DMA service from and configure the DMA controller+
−
to route sources to allocated channels accordingly. </p> <p>The platform-specific+
−
cookies passed by client device drivers to the PSL must be defined somewhere+
−
so that client device drivers can access them. </p> </section>+
−
<section id="GUID-6B35E9A7-11D6-5B26-B562-934169503412"><title>[Optionally]+
−
implement channel cleanup</title> <p>In the template PSL (platform-specific+
−
layer), the function <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-909D795A-7303-3A76-9C8E-3B07A97DD716"><apiname>DmaChannelMgr::Close()</apiname></xref> is a no-operation.+
−
This function is called by the PIL (platform-independent layer) when client+
−
device drivers call <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-8204AFBD-2A60-372E-B626-35BD19851FF7"><apiname>TDmaChannel::Close()</apiname></xref>. If the PSL needs+
−
to perform any hardware-specific operation when the channel is closed, then+
−
the implementation of <codeph>DmaChannelMgr::Close()</codeph> should be updated+
−
to reflect that. </p> </section>+
−
<section id="GUID-C9439F04-0BCC-5BC7-B18B-5C1B88515340"><title>Implement the+
−
mandatory controller virtual functions</title> <p>The <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> class+
−
contains several pure virtual functions that must be implemented by the PSL+
−
(platform-specific layer): </p> <ul>+
−
<li id="GUID-FF533DDF-E4B1-5AD1-9CBD-19A1D94AB07D"><p> <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-81921A9D-41F5-34BC-B882-60CC4CD807FB"><apiname>TDmac::Transfer()</apiname></xref>  </p> </li>+
−
<li id="GUID-F6D6524A-09E3-54C0-AEB6-1D6BAB29210C"><p> <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-B738D1B9-80FA-334D-ABEB-DFFF093E0B9D"><apiname>TDmac::StopTransfer()</apiname></xref>  </p> </li>+
−
<li id="GUID-6209F3C7-9E3C-58BF-ABA4-6DF4BBF44A82"><p> <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-7422834D-CE6B-32DB-A040-7762A8BAB7D7"><apiname>TDmac::IsIdle()</apiname></xref>  </p> </li>+
−
</ul> <p>These functions start and stop transfers on a DMA channel and are+
−
the main interface between the PIL (platform-independent layer) and the PSL.+
−
The implementation of these functions depends on the hardware available for+
−
performing DMA, and on the characteristics used to specify a DMA transfer: </p> <ul>+
−
<li id="GUID-81DA9FED-18F0-5205-9597-33542B0CB3CC"><p>the source and destination+
−
addresses </p> </li>+
−
<li id="GUID-D6684249-31CC-544B-8CEE-DD1D7FC8A8A1"><p>the burst size </p> </li>+
−
<li id="GUID-91D910DB-E1D7-5993-9ADB-6823662249D0"><p>the maximum transfer+
−
size </p> </li>+
−
<li id="GUID-C1926D7D-8349-5BA1-8E21-AB5D90486443"><p>the transfer width,+
−
i.e. number of bits per memory access </p> </li>+
−
<li id="GUID-C091D505-1088-56CA-8630-F1099B0A2234"><p>the memory alignment+
−
and endianness. </p> </li>+
−
</ul> <p>The DMA Framework manages the transfer descriptors according to the+
−
descriptor parameter passed into the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> constructor+
−
by the derived class constructor; the descriptor parameter is a <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-BBD2153C-4B41-357C-9299-D710930AFCBE"><apiname>TDmac::SCreateInfo</apiname></xref> structure.+
−
The per-request transfer parameters are passed into the descriptors for each+
−
request issued by a driver. </p> <p><b>The+
−
transfer function: Transfer()</b> </p> <p>This function initiates a previously+
−
constructed request on a specific channel. This is the template implementation: </p> <codeblock id="GUID-80B95C0E-B30D-5A10-8512-68317D404DB3" xml:space="preserve">void TTemplateDmac::Transfer(const TDmaChannel&amp; aChannel, const SDmaDesHdr&amp; aHdr)+
−
//+
−
// Initiates a (previously constructed) request on a specific channel.+
−
//+
−
    {+
−
    const TUint8 i = static_cast&lt;TUint8&gt;(aChannel.PslId());+
−
    TDmaDesc* pD = HdrToHwDes(aHdr);+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("&gt;TTemplateDmac::Transfer channel=%d des=0x%08X", i, pD));+
−
+
−
    // TO DO (for instance): Load the first descriptor address into the DMAC and start it+
−
    // by setting the RUN bit.+
−
    (void) *pD, (void) i;+
−
+
−
    }+
−
        </codeblock> <p><b>The+
−
stop transfer function: StopTransfer()</b> </p> <p>This function requires+
−
that the RUN mode is cleared. This is the template implementation: </p> <codeblock id="GUID-1BF7A5B4-2723-5A18-98E0-1F79A4928121" xml:space="preserve">void TTemplateDmac::StopTransfer(const TDmaChannel&amp; aChannel)+
−
//+
−
// Stops a running channel.+
−
//+
−
    {+
−
    const TUint8 i = static_cast&lt;TUint8&gt;(aChannel.PslId());+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("&gt;TTemplateDmac::StopTransfer channel=%d", i));+
−
+
−
    // TO DO (for instance): Clear the RUN bit of the channel.+
−
    (void) i;+
−
+
−
    }+
−
        </codeblock> <p><b>The+
−
function: IsIdle()</b> </p> <p> <codeph>IsIdle()</codeph> returns the state+
−
of a given channel. This is the template implementation: </p> <codeblock id="GUID-C7CC986E-986B-5C5E-AA3D-86851131BE93" xml:space="preserve">TBool TTemplateDmac::IsIdle(const TDmaChannel&amp; aChannel)+
−
//+
−
// Returns the state of a given channel.+
−
//+
−
    {+
−
    const TUint8 i = static_cast&lt;TUint8&gt;(aChannel.PslId());+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("&gt;TTemplateDmac::IsIdle channel=%d", i));+
−
+
−
    // TO DO (for instance): Return the state of the RUN bit of the channel.+
−
    // The return value should reflect the actual state.+
−
    (void) i;+
−
+
−
    return ETrue;+
−
    }+
−
        </codeblock> </section>+
−
<section id="GUID-A362A7CF-3674-525C-8114-485315E6594B"><title>Implement the+
−
non-mandatory controller virtual functions</title> <p>The following auxiliary+
−
functions are used to implement the scatter-gather transfer mode behaviour+
−
by creating and manipulating the linked list of transfer fragment headers+
−
that describe a given scatter-gather transaction. They are called by the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> base+
−
class functions when the instance of the <codeph>TDmac</codeph> derived class+
−
reports itself as being capable of scatter-gather operations. </p> <ul>+
−
<li id="GUID-D401D7C8-B086-56CD-BAE0-96EEB0AA7E38"><p> <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-90AC3E58-E589-3F91-85F7-16A4ADFFFA69"><apiname>TDmac::InitHwDes()</apiname></xref>  </p> </li>+
−
<li id="GUID-58633367-FE56-53B7-A967-21828DA85F5C"><p> <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-05021B05-75DE-3F75-92C6-8B9445EB86D3"><apiname>TDmac::ChainHwDes()</apiname></xref>  </p> </li>+
−
<li id="GUID-94F81366-77D4-5AF6-9933-53E964863301"><p> <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-AFCDDA16-991D-3BDA-B90B-87BCAFF66E5C"><apiname>TDmac::AppendHwDes()</apiname></xref>  </p> </li>+
−
</ul> <p><b>First+
−
scatter-gather support function: InitHwDes()</b> </p> <p>This is a function+
−
for creating a scatter-gather list. From the information in the passed-in+
−
request, the function sets up the descriptor with that fragment's: </p> <ul>+
−
<li id="GUID-098E886D-D98D-5AC9-BB25-7FF8E6F0D05B"><p>source and destination+
−
address </p> </li>+
−
<li id="GUID-83440454-B955-55C8-BF10-DF86CDA0C466"><p>size </p> </li>+
−
<li id="GUID-294D3B08-0A64-534D-858F-F43759A2DC59"><p>driver/DMA controller+
−
specific transfer parameters: memory/peripheral, burst size, transfer width. </p> </li>+
−
</ul> <p>This is the template implementation: </p> <codeblock id="GUID-EB6F9C76-EC23-5464-A6C5-AB0B36717D2B" xml:space="preserve">void TTemplateDmac::InitHwDes(const SDmaDesHdr&amp; aHdr, TUint32 aSrc, TUint32 aDest, TInt aCount,+
−
                              TUint aFlags, TUint32 aPslInfo, TUint32 /*aCookie*/)+
−
//+
−
// Sets up (from a passed in request) the descriptor with that fragment's source and destination address,+
−
// the fragment size, and the (driver/DMA controller) specific transfer parameters (mem/peripheral,+
−
// burst size, transfer width).+
−
//+
−
    {+
−
    TDmaDesc* pD = HdrToHwDes(aHdr);+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("TTemplateDmac::InitHwDes 0x%08X", pD));+
−
+
−
    // Unaligned descriptor? Error in generic layer!+
−
    __DMA_ASSERTD(IsHwDesAligned(pD));+
−
+
−
    pD-&gt;iSrcAddr = (aFlags &amp; KDmaPhysAddrSrc) ? aSrc : Epoc::LinearToPhysical(aSrc);+
−
    pD-&gt;iDestAddr = (aFlags &amp; KDmaPhysAddrDest) ? aDest : Epoc::LinearToPhysical(aDest);+
−
    pD-&gt;iCmd = DcmdReg(aCount, aFlags, aPslInfo);+
−
    pD-&gt;iDescAddr = TDmaDesc::KStopBitMask;+
−
    }+
−
+
−
          </codeblock> <p><b>Second+
−
scatter-gather support function: ChainHwDes()</b> </p> <p>If the framework+
−
needs to fragment the client’s request, for transfer size or memory discontiguousness+
−
reasons, then the framework calls this function. It chains hardware descriptors+
−
together by setting the next pointer of the original descriptor to the physical+
−
address of the descriptor to be chained. It assumes that the DMAC channel+
−
is quiescent when called. </p> <p>This is the template implementation: </p> <codeblock id="GUID-7979A1FB-5FA1-5078-8762-3874A62E6C63" xml:space="preserve">void TTemplateDmac::ChainHwDes(const SDmaDesHdr&amp; aHdr, const SDmaDesHdr&amp; aNextHdr)+
−
//+
−
// Chains hardware descriptors together by setting the next pointer of the original descriptor+
−
// to the physical address of the descriptor to be chained.+
−
//+
−
    {+
−
    TDmaDesc* pD = HdrToHwDes(aHdr);+
−
    TDmaDesc* pN = HdrToHwDes(aNextHdr);+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("TTemplateDmac::ChainHwDes des=0x%08X next des=0x%08X", pD, pN));+
−
+
−
    // Unaligned descriptor? Error in generic layer!+
−
    __DMA_ASSERTD(IsHwDesAligned(pD) &amp;&amp; IsHwDesAligned(pN));+
−
+
−
    // TO DO: Modify pD-&gt;iCmd so that no end-of-transfer interrupt gets raised any longer.+
−
+
−
    pD-&gt;iDescAddr = DesLinToPhys(pN);+
−
    }+
−
+
−
</codeblock> <p><b>Third+
−
scatter-gather support function: AppendHwDes()</b> </p> <p>This function is+
−
called by the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> base class when a driver request is+
−
called for a channel that is still active, i.e. where the intent is to provide+
−
data streaming so that the target device is constantly provided with data;+
−
for example, an audio device playing a track. In this case, the function provided+
−
by the derived class must: </p> <ul>+
−
<li id="GUID-F94FBAA8-2A0D-5863-BA09-0EC1D61005A9"><p>stop the DMAC to prevent+
−
any corruption of the scatter-gather list while appending the new fragment+
−
descriptor </p> </li>+
−
<li id="GUID-AEF81B78-73D8-5B70-AFE4-0AEA7862CB74"><p>append the new descriptor </p> </li>+
−
<li id="GUID-2304F2D4-833E-5F75-B88E-C794DF9D984E"><p>re-enable the channel,+
−
ideally before the target has detected the gap in service. </p> </li>+
−
</ul> <p>This is the template implementation: </p> <codeblock id="GUID-18512439-C781-5267-ADBC-B9047942F800" xml:space="preserve">void TTemplateDmac::AppendHwDes(const TDmaChannel&amp; aChannel, const SDmaDesHdr&amp; aLastHdr,+
−
                                const SDmaDesHdr&amp; aNewHdr)+
−
//+
−
// Appends a descriptor to the chain while the channel is running.+
−
//+
−
    {+
−
    const TUint8 i = static_cast&lt;TUint8&gt;(aChannel.PslId());+
−
+
−
    TDmaDesc* pL = HdrToHwDes(aLastHdr);+
−
    TDmaDesc* pN = HdrToHwDes(aNewHdr);+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("&gt;TTemplateDmac::AppendHwDes channel=%d last des=0x%08X new des=0x%08X",+
−
                                    i, pL, pN));+
−
    // Unaligned descriptor? Error in generic layer!+
−
    __DMA_ASSERTD(IsHwDesAligned(pL) &amp;&amp; IsHwDesAligned(pN));+
−
+
−
    TPhysAddr newPhys = DesLinToPhys(pN);+
−
+
−
    const TInt irq = NKern::DisableAllInterrupts();+
−
    StopTransfer(aChannel);+
−
+
−
    pL-&gt;iDescAddr = newPhys;+
−
    const TTemplateSgChannel&amp; channel = static_cast&lt;const TTemplateSgChannel&amp;&gt;(aChannel);+
−
    TDmaDesc* pD = channel.iTmpDes;+
−
+
−
    // TO DO: Implement the appropriate algorithm for appending a descriptor here.+
−
    (void) *pD, (void) i;+
−
+
−
    NKern::RestoreInterrupts(irq);+
−
+
−
    __KTRACE_OPT(KDMA, Kern::Printf("&lt;TTemplateDmac::AppendHwDes"));+
−
    }+
−
    </codeblock> </section>+
−
<section id="GUID-F5968000-0C3E-5E53-A2D5-120B81F3140F"><title>Implement an+
−
interrupt service routine</title> <p>The interrupt service routine needs to+
−
do the following: </p> <ul>+
−
<li id="GUID-CE55E999-0886-5620-87BA-99A36D694FD4"><p>identify the channel+
−
that raised the interrupt </p> </li>+
−
<li id="GUID-02467F17-DC1E-552C-B1C2-D3C2CCE12347"><p>decide whether the interrupt+
−
was raised because of a successful data transfer or because of an error </p> </li>+
−
<li id="GUID-0D5FDA57-A45E-54E5-A69C-64D22B916AB4"><p>call the base class+
−
function <codeph>TDmac::HandleIsr()</codeph>, which queues a DFC, or increments+
−
the number of pending interrupts if a DFC is already queued. </p> </li>+
−
</ul> <p>This is the template implementation: </p> <codeblock id="GUID-4CFCA5A1-9657-55F1-BE3C-AFF1F3974F80" xml:space="preserve">void TTemplateDmac::Isr(TAny* aThis)+
−
//+
−
// This ISR reads the interrupt identification and calls back into the base class+
−
// interrupt service handler with the channel identifier and an indication whether the+
−
// transfer completed correctly or with an error.+
−
//+
−
    {+
−
    TTemplateDmac&amp; me = *static_cast&lt;TTemplateDmac*&gt;(aThis);+
−
+
−
    // TO DO: Implement the behaviour described above, call HandleIsr().+
−
+
−
    HandleIsr(me.iChannels[5], 0);                            // Example+
−
+
−
    }+
−
     </codeblock> </section>+
−
<section id="GUID-D7F410A1-DC70-515D-A00D-3955B534C62F"><title>Implement the+
−
test support table and function</title> <p>The DMA Framework comes with a+
−
test harness that can be used to validate the port if the underlying DMA controller+
−
supports memory to memory transfers. </p> <p>The test harness needs to know+
−
about the capabilities of the port being tested. The PSL provides the global+
−
function <xref href="GUID-3D0A9A03-E210-30EE-A1A1-7DA06E668CAA.dita"><apiname>DmaTestInfo()</apiname></xref> that returns a <xref href="GUID-59EE15C1-19E7-3AA7-8339-A80CCC074D64.dita"><apiname>TDmaTestInfo</apiname></xref> object+
−
that contains this information. In the template PSL, this structure is initialised+
−
to binary zeroes. Before using the test harness, it must be initialised with+
−
valid values. </p> <p>See <xref href="GUID-59EE15C1-19E7-3AA7-8339-A80CCC074D64.dita"><apiname>TDmaTestInfo</apiname></xref>, <xref href="GUID-3D0A9A03-E210-30EE-A1A1-7DA06E668CAA.dita"><apiname>DmaTestInfo()</apiname></xref> and <xref href="GUID-8552E66E-73D6-51DA-8F53-DDF437186CD6.dita">Validation</xref>. </p> </section>+
−
<section id="GUID-D452D2CD-D251-50F4-818E-E7125501CE8F"><title>Optimise the+
−
performance of critical functions</title> <p>You can optionally optimise critical+
−
functions by writing them in assembler. The two candidates for an assembler+
−
rewrite are: </p> <ul>+
−
<li id="GUID-157E6F4A-0310-5923-B446-040F75E469D4"><p>The interrupt service+
−
routine </p> </li>+
−
<li id="GUID-74C9D4DB-9CA9-5C5E-A475-B6840EBC2245"><p>In scatter-gather mode,+
−
the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-AFCDDA16-991D-3BDA-B90B-87BCAFF66E5C"><apiname>TDmac::AppendHwDes()</apiname></xref> function if it needs to suspend+
−
a transfer when appending a new descriptor chain to an existing one. </p> </li>+
−
</ul> </section>+
−
<section id="GUID-A2AF293F-558A-5F69-821F-EC2B202A5A4F"><title>Extend the+
−
framework with platform-specific functionality</title> <p>There are two ways+
−
of extending the DMA Framework: </p> <ol id="GUID-D6C660FC-FF23-55B2-B91E-4BC04C592059">+
−
<li id="GUID-4453F4C2-3444-5A3E-94C7-BE6320B1EF89"><p>to provide platform-specific+
−
functionality on a per-channel basis. </p> </li>+
−
<li id="GUID-C0C6A072-134A-5753-A6DC-185F3975C2A6"><p>to provide platform-specific+
−
functionality on a <i>channel independent</i> basis. </p> </li>+
−
</ol> <p>In the first case, the PSL provides an implementation of the virtual+
−
function <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-D6D011E9-9D75-3881-87D8-1986FFBBA106"><apiname>TDmac::Extension()</apiname></xref>. The default implementation+
−
just returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p> <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-2CF7498E-F5D2-3C4A-8E98-47504F9FC404"><apiname>TDmaChannel::Extension()</apiname></xref> calls <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-D6D011E9-9D75-3881-87D8-1986FFBBA106"><apiname>TDmac::Extension()</apiname></xref>. </p> <p>In the second case, the PSL provides an implementation of the static+
−
function <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-C733B302-4269-3391-8ADE-617CFF198B56"><apiname>DmaChannelMgr::StaticExtension()</apiname></xref>. The template+
−
PSL implementation just returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p> <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-75562653-1F27-39D3-96D8-55A94BA9B68B"><apiname>TDmaChannel::StaticExtension()</apiname></xref> calls <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-C733B302-4269-3391-8ADE-617CFF198B56"><apiname>DmaChannelMgr::StaticExtension()</apiname></xref>. </p> </section>+
−
</conbody></concept>+
−