<?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>