<?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-43782364-0865-43D0-BC89-D63BA9912FB6" xml:lang="en"><title>Basic Management</title><shortdesc>This document describes how device drivers should manage shared

chunks.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-A30FD089-100B-44A3-B174-A68C7BC00372"><title>Creation</title> <p>A

shared chunk is created in kernel space. The user is given a handle to the

shared chunk to access it, and can pass the handle to other process or other

drivers. Chunks are represented by <xref href="GUID-85454082-6734-3F1D-983F-734D4C2AB12D.dita"><apiname>DChunk</apiname></xref> objects on the

kernel side and by <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> on the user side. </p> <p>A shared

chunk is created by using <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-F8D1FB29-7238-3438-951A-6F853C7CF817"><apiname>Kern::ChunkCreate()</apiname></xref>, which takes

a <xref href="GUID-51F7DBCF-BFB6-31F9-8882-5D263A1AD4B4.dita"><apiname>TChunkCreateInfo</apiname></xref> argument that sets the chunk properties. </p> <p>Chunk

creation should be done in a critical section, created using <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-841D587C-E9E6-34EE-8ED0-E9A206F64379"><apiname>NKern::ThreadEnterCS()</apiname></xref> and <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2C897BA5-2BD7-3ABA-9F2B-F0B1AC14D1AE"><apiname>NKern::ThreadLeaveCS()</apiname></xref>. The size of the chunk should be in multiples of MMU pages, which can be

calculated using <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-B37D12CF-449A-3EC3-9C4F-854A35E98CE3"><apiname>Kern::RoundToSize(n)</apiname></xref>, where <varname>n</varname> is

the actual size that needs to be rounded. </p> <codeblock id="GUID-5F307D2C-517B-505D-A8D3-A4820B612E53" xml:space="preserve">/**

 Create a transmit shared chunk of specified size.

 @param    aChunkSize

         size of the chunk to be created

 @return    KErrNone on success, standard error code on failure

 */    

TInt DExUartPhysicalChannel::CreateTxChunk(TUint aChunkSize)

    {

    ...

    // 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). 

    size=Kern::RoundToPageSize(aChunkSize);

    // Thread must be in critical section 

    NKern::ThreadEnterCS();

    ...

    // Create the chunk. Example is given in next code snippet

    ...

    // Commit the chunk. Example is given in following sections

    ...

    // Thread can leave the critical section 

    NKern::ThreadLeaveCS();

    }

TInt DExUartPhysicalChannel::CreateTxChunk(TUint aChunkSize)

    {

    ...

    NKern::ThreadLeaveCS(); // Enter the critical section

    // TChunkCreateInfo holds the parameters required to create a 

    // chunk and is used by Kern::ChunkCreate()

    TChunkCreateInfo info;

    // ESharedKernelMultiple specifies that a chunk which may be opened by 

    // any number of user side processes

    info.iType=TChunkCreateInfo::ESharedKernelMultiple;        

    info.iMaxSize= size;        // Chunk size

    // This specifies the caching attributes for the chunk. It can 

    // be no caching or fully caching (TMappingAttributes enum 

    // type). If the MMU does not support the requested attributes,  

    // then a lesser cached attribute will be used. The actual 

    // value used is returned in aMapAttr of Kern::ChunkCreate() 

    info.iMapAttr=EMapAttrFullyBlocking; // No Caching, suitable for DMA

    // Set to true if the chunk is to own its committed memory. 

    // In this case all memory committed to the chunk will come 

    // from the system's free pool and will be returned there when 

    // the chunk is destroyed. If the chunk will be committed to 

    // physical address, then EFalse can be set.

    info.iOwnsMemory=ETrue;            // using RAM pages

    // As chunk destruction is asynchronous we can have 

    // a DFC, if required, specifying a callback function to get 

    // the chunk destroy notification exactly. This is used if any 

    // follow up cleaning has to be done after chunk destruction.

    info.iDestroyedDfc=NULL;    // No chunk destroy DFC.

    DChunk* chunk;

    TUint32 mapAttr;

    // Creates a chunk that can be shared between a user thread and a 

    // kernel thread. This will be the initial step for a shared 

    // chunk. Once created, the chunk owns a region of linear 

    // address space of the requested size. This region is empty 

    // (uncommitted) so before it can be used either RAM or I/O 

    // devices must be mapped into it. This is achieved with the 

    // Commit functions.

    // Here iTxChunkKernAddr returns the linear address of the 

    // chunk created.

    //

    TInt r=Kern::ChunkCreate(info,chunk,iTxChunkKernAddr, mapAttr);

    if (r!=KErrNone)

        {

        // Thread can leave the critical section

        NKern::ThreadLeaveCS();

        return r;

        }

    ...

    }</codeblock> </section>

<section id="GUID-84D1C7D6-5EFE-4D88-BC87-1D8897693B8A"><title>Destruction</title> <p>To allow a chunk to be properly cleaned

up, a driver should close the chunk when it is no longer required. When a

chunk is closed, the reference count is decremented by one. The chunk gets

destroyed when the reference count becomes zero. Closing the chunk should

be done within a critical section. </p> <p>The destruction of the chunk happens

asynchronously, and a notification of this can be requested. This is done

using a DFC, by initialising <xref href="GUID-51F7DBCF-BFB6-31F9-8882-5D263A1AD4B4.dita#GUID-51F7DBCF-BFB6-31F9-8882-5D263A1AD4B4/GUID-F6394BC5-16A9-383B-8E5D-446FB3136762"><apiname>TChunkCreateInfo::iDestroyDfc()</apiname></xref> with

the DFC object. </p> <codeblock id="GUID-14F48A69-FCDF-5D5A-A6C6-42E4D57CB497" xml:space="preserve">/**

 Close the transmit chunk, that was already created. This is 

 called while closing the logical channel

 */

void DExUartPhysicalChannel::CloseTxChunk()

    {

    // Thread must be in critical section

    NKern::ThreadEnterCS();

    // Atomically get pointer to our chunk and NULL the iChunk 

    // member. Nkern::SafeSwap() atomically replaces the word 

    // referenced by aPtr with aNewValue, here NULL.

    //

 DChunk* chunk = (DChunk*)NKern::SafeSwap(NULL,(TAny*&)iTxChunk);

    if (chunk)

        {

        // Close the chunk that was created. This should be 

        // done in a critical section. This function decrements 

        // a chunk's access count, and, if the count reaches 

        // zero, the chunk is scheduled for destruction.

        // ChunkClose() has to be called the same number of times 

        // as chunk creation. A mismatch in this will result 

        // in either a memory leak or a panic.

        //

        Kern::ChunkClose(chunk);

        }

    // Thread can leave the critical section    

    NKern::ThreadLeaveCS();        

    }</codeblock></section>

<section id="GUID-2CCEB305-03D7-44A4-A489-3B00680383F9"><title>Mapping</title> <p>Shared chunks must be mapped to memory,

which means that either RAM or an I/O device must be committed to a shared

chunk before it can be used. This maps the chunk to a certain address. The

memory can be physical contiguous RAM pages, an arbitrary set of RAM pages,

a physical region, or a physical region with a list of physical addresses.

The Kernel provides the following APIs for committing these types of memory: </p> <codeblock id="GUID-256A14F7-D9D8-528A-8E8A-C573A492F803" xml:space="preserve">// Commit RAM to a shared chunk. The memory pages to commit are 

// obtained from the system's free pool

TInt Kern::ChunkCommit(DChunk *aChunk, TInt aOffset, TInt aSize);

// Commit RAM to a shared chunk. The memory pages to commit are 

// obtained from the system's free pool and will have physically 

// contiguous addresses. Used when TChunkCreateInfo::iOwnsMemory 

// is ETrue

TInt Kern::ChunkCommitContiguous(DChunk *aChunk, TInt aOffset, 

                TInt aSize, TUint32 &aPhysicalAddress);

// Commit memory to a shared chunk. The physical region committed 

// is that which starts at the supplied physical address. 

// Typically, this region either represents memory mapped I/O, or 

// RAM that was set aside for special use at system boot time. 

// This is used when TChunkCreateInfo::iOwnsMemory is EFalse.

TInt Kern::ChunkCommitPhysical(DChunk *aChunk, TInt aOffset, 

                TInt aSize, TUint32 aPhysicalAddress);

// Commit memory to a shared chunk. The physical region committed

// is determined by the list of physical addresses supplied to 

// this function

TInt Kern::ChunkCommitPhysical(DChunk *aChunk, TInt aOffset, 

        TInt aSize, const TUint32 *aPhysicalAddressList);

</codeblock></section>