<?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-E7E67A52-0725-446B-A49C-CF571C4A0C64" xml:lang="en"><title>DMA
Buffer Operations</title><shortdesc>This document describes how a device driver allocates and deallocates
DMA buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-74A2C413-DF2C-4DB6-917B-A4B6CD05612F"><title> Allocation</title> <p>DMA
requires contiguous memory chunks to be allocated to do copy and read operations.
A driver can do this by using the Symbian Kernel API. A contiguous block of
memory can be allocated using <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-B506D835-505D-3D89-A840-475F291908DC"><apiname>Epoc::AllocPhysicalRam()</apiname></xref>,
which provides the physical address of the contiguous memory block allocated. </p> <p>After
allocating the buffer, a global hardware chunk must be created, and its attributes
set. The attributes define chunk properties such as whether it is non-cacheable,
or whether it can be accessed only in supervisor mode, and so on. </p> <codeblock id="GUID-69AB812C-2497-5005-9BA4-F78BA6DB5A52" xml:space="preserve">TInt DExDriverUartTxDma::Init()
    {
    // Round up the transmit chunk size to the page size.     
    // Kern::RoundToPageSize() rounds up the argument to the size of 
    // a MMU page. The size of one MMU page can be found out by calling 
    // Kern::RoundToPageSize(1).
    //
    iTxBufSize = Kern::RoundToPageSize (KRxTxDMABufferSize);

    // Epoc::AllocPhysicalRam() allocate contiguous physical memory 
    // for the transmit buffer of the specified size, and returns the physical address 
    // of the buffer. We need contiguous block of memory and its 
    // physical address for DMA.
    //
    TInt r = Epoc::AllocPhysicalRam (iTxBufSize, iTxPhysAddr);
    if (r != KErrNone)
        {
        return r;
        }

    // Create a global hardware chunk for the buffer allocated using 
    // Epoc::AllocPhysicalRam() and set attributes to make it 
    // uncached and accessible only by kernel-side code. 
    // Contiguous, uncached, unbuffereable RAM pages avoids 
    // coherency and fragmentation issues while using DMA.
    // However, in case of making buffers cacheable other APIs are     
    // provided to synch, i.e. flush cache before doing a DMA 
    // transfer 
    // 
    r = DPlatChunkHw::New(iTxChunk, iTxPhysAddr, iTxBufSize,
    EMapAttrSupRw // Supervisor mode, user has no access
    |EMapAttrFullyBlocking); // uncached, unbuffered    
    if (r != KErrNone)
        {
        // Free the allocated RAM, that was earlier allocated by         
        // Epoc::AllocPhysicalRam(). 
        Epoc::FreePhysicalRam(iTxPhysAddr, iTxBufSize);
        return r;
        }
    ...
    }</codeblock> <p>Buffers can also be made cacheable, in which case, the
driver has to ensure to synchronise by flushing the cache before writing and
after reading. </p> <codeblock id="GUID-8C452D9B-6674-5B2F-931B-7C671F9E60DC" xml:space="preserve">// Synchronises cache(s) prior to a DMA write operation. i.e. 
// before DMA is used write to a peripheral data which is read 
// from RAM.
void Cache::SyncMemoryBeforeDmaWrite(TLinAddr aBase, 
                TUint aSize, TUint32 aMapAttr)

// Synchronizes cache(s) prior to a DMA read operation.
// i.e. before DMA is used read from a peripheral data which is 
// written to RAM.
void Cache::SyncMemoryBeforeDmaRead(TLinAddr aBase, 
                TUint aSize, TUint32 aMapAttr)

// Synchronises cache(s) after a DMA read operation.
void Cache::SyncMemoryAfterDmaRead(TLinAddr aBase, TUint aSize)</codeblock> <p>However,
unless required by design, DMA chunks are used in non-cacheable and non-buffered
mode. </p></section>
<section id="GUID-76E909F6-65D5-41BB-8B86-03801F42C8D6"><title>Deallocation</title> <p>DMA buffers have to be deallocated
when they are no longer used. Buffers are deallocated in the physical channel
destructor. </p> <p>Like allocation, deallocation is performed in two stages.
When you allocate, the contiguous buffer is allocated and a hardware chunk
is created; when you de-allocate, the contiguous buffer is deallocated and
the chunk is closed. </p></section>
</conbody></concept>