--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-E7E67A52-0725-446B-A49C-CF571C4A0C64.dita	Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,86 @@
+<?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>
\ No newline at end of file