<?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-8F1567B4-6957-5B93-9499-35489AD610F5" xml:lang="en"><title>Chunks</title><shortdesc>Chunks map RAM or memory-mapped I/O devices into contiguous virtual

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

<p> A chunk consists of a <i>reserved</i> region and a <i>committed</i> region.

The reserved region is the contiguous set of virtual addresses accessible

to running code. The committed region is the region in which RAM (or memory-mapped

I/O) is actually mapped. The size of a chunk is dynamically alterable, allowing

the committed region to vary in size from zero up to the reserved region size,

in integer multiples of the processor page size. This allows processes to

obtain more memory on demand. Generally the committed region starts at the

bottom of the reserved region. </p>

<p>A chunk also has a maximum size, which is defined when the chunk is created.

The reserved region can be smaller than this maximum size, but it can also

be made bigger by reallocating it. The reserved region cannot be made bigger

than the maximum size. </p>

<p>The size of the reserved region of a chunk is always an integer multiple

of the virtual address range of a single entry in the processor page directory

(PDE size). This means that the reserved region of a chunk is mapped by a

number of consecutive page directory entries (PDEs). Any given PDE maps part

of the reserved region of at most one chunk. </p>

<p>Symbian platform has a number of chunk types, but for user side code, the

chunks of interest are <i>User chunks</i> and <i>Shared chunks</i>. </p>

<p>A chunk is a kernel side entity, and like all other kernel side entities,

it is accessed from the user side using a handle, an instance of the <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> class.

The concept of <i>local</i> and <i>global</i> also applies to chunks. </p>

<ul>

<li id="GUID-8F4C6D46-8A0D-582F-9CA3-B6E256A32A04"><p> <xref href="GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita#GUID-8F1567B4-6957-5B93-9499-35489AD610F5/GUID-F16E4C51-975B-58D6-808B-A865389AEF08">User chunks</xref>  </p> </li>

<li id="GUID-FF713424-EAAA-576A-8559-5DC69FCE92DB"><p> <xref href="GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita#GUID-8F1567B4-6957-5B93-9499-35489AD610F5/GUID-FD985769-32EB-5A8C-97E8-A3D2D89BBC33">Shared chunks</xref>  </p> </li>

<li id="GUID-DE72ABC0-787D-5CB9-90B8-E5B9CA230105"><p> <xref href="GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita#GUID-8F1567B4-6957-5B93-9499-35489AD610F5/GUID-8E371955-C475-5980-A04F-B33EAADE1B1B">Local and global chunks</xref>  </p> </li>

</ul>

<section id="GUID-F16E4C51-975B-58D6-808B-A865389AEF08"><title>User chunks</title> <p>On

systems with an MMU, Symbian platform provides three types of user chunks.

Each type is characterised by having a different subset of the reserved address

range containing committed memory: </p> <ul>

<li id="GUID-7466E379-0AEE-5302-B553-D2983612B0E7"><p> <xref href="GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita#GUID-8F1567B4-6957-5B93-9499-35489AD610F5/GUID-F0DB5A9F-EB24-5D2B-B2A8-90EEE2A2C33F">Normal chunks</xref>  </p> </li>

<li id="GUID-12C654CE-8608-55AB-A8F9-D261E5286521"><p> <xref href="GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita#GUID-8F1567B4-6957-5B93-9499-35489AD610F5/GUID-0FB877CD-C4E1-5253-AFBC-563E3C715A44">Double-ended chunks</xref> </p> </li>

<li id="GUID-26A7095A-36D4-508A-A2EB-6525540B5C3F"><p> <xref href="GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita#GUID-8F1567B4-6957-5B93-9499-35489AD610F5/GUID-230B66B1-7FD8-5944-9284-354C7564156B">Disconnected chunks</xref>  </p> </li>

</ul> <p id="GUID-F0DB5A9F-EB24-5D2B-B2A8-90EEE2A2C33F"><b>Normal chunks</b> </p> <p>These

chunks have a committed region consisting of a single contiguous range starting

at the chunk's base address and a size that is a multiple of the MMU page

size. The following diagram is an example of this kind of chunk: </p> <fig id="GUID-BD64E013-2750-5298-8C5A-8DAC9AB30E14">

<title>Normal chunks</title>

<image href="GUID-07F65EEA-5969-5E56-9570-245712FB3EE3_d0e240067_href.png" placement="inline"/>

</fig> <p id="GUID-0FB877CD-C4E1-5253-AFBC-563E3C715A44"><b>Double-ended chunks</b> </p> <p>These

chunks have a committed region consisting of a single contiguous range starting

at arbitrary lower and upper endpoints within the reserved region. The only

condition is that the lower and upper endpoints must be a multiple of the

MMU page size. Both the bottom and top of the committed region can be altered

dynamically. The following diagram shows an example of this kind of chunk: </p> <fig id="GUID-62D7BB5C-3BF1-5AA1-88A2-45D09D8684C9">

<title>Double-ended chunks</title>

<image href="GUID-99C2E42F-1029-5E32-8446-CAAF29D733BA_d0e240083_href.png" placement="inline"/>

</fig> <p id="GUID-230B66B1-7FD8-5944-9284-354C7564156B"><b>Disconnected chunks</b> </p> <p>These

chunks have a committed region consisting of an arbitrary set of MMU pages

within the reserved region. Each page-sized address range within the reserved

region starting on a page boundary can be committed independently. The following

diagram shows an example of this kind of chunk: </p> <fig id="GUID-13C9EED8-9C28-5289-A558-378DE49A0DAF">

<title>Disconnected chunks</title>

<image href="GUID-59C143F6-3A0C-5C37-9351-A72FE45AFFC9_d0e240099_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-FD985769-32EB-5A8C-97E8-A3D2D89BBC33"><title>Shared chunks</title> <p>A

shared chunk is a mechanism that allows kernel-side code to share memory buffers

safely with user-side code. By kernel-side code, we usually mean device driver

code. </p> <p>The main points to note about shared chunks are: </p> <ul>

<li id="GUID-256C4B04-4B8E-5FDF-AF3B-703936BB2674"><p>They can only be created

and destroyed by device drivers. It is typical behaviour for user-side code,

which in this context we refer to as the client of the device driver, to pass

a request to the device driver to open a handle to a shared chunk. This causes

the device driver to open a handle to the chunk and return the handle <i>value</i> to

the client. Successful handle creation also causes the chunk's memory to be

mapped into the address space of the process to which the client's thread

belongs. Note, however, that it is the driver that dictates exactly when the

chunk itself is created, and when memory is committed. The precise protocol

depends on the design of the driver; you need to refer to that driver's documentation

for programming guidance. </p> </li>

<li id="GUID-8FACA759-AE5C-5723-A01C-4E39B50B55C0"><p>Like all kernel side

objects, a shared chunk is reference counted. This means that it remains in

existence for as long as the reference count is greater than zero. Once all

opened references to the shared chunk have been <i>closed</i>, regardless

of whether the references are user-side, or kernel-side, then it is destroyed. </p> </li>

<li id="GUID-FD61FB5B-E0E8-52B2-8DE0-1E9425B28C2F"><p>User-side code that

has gained access to a shared chunk from one device driver can pass this to

a second device driver. The second device driver must <i>open</i> the chunk

before it can be used. </p> </li>

<li id="GUID-989692D2-60C2-5B71-879F-6C4A9C7F348B"><p>More than one user side

application can access the data in a shared chunk. A handle to a shared chunk

can be passed from one process to another process using standard handle passing

mechanisms. In practice, handles would be passed in a client-server context,

either from client to server or from server to client using inter-process

communication (IPC). </p> </li>

<li id="GUID-20FF4363-CC7D-5CFB-863C-420A16362B21"><p>Processes that share

data inside a chunk should communicate the location of that data as an offset

from the start of the chunk, and <i>not</i> as an absolute address. The shared

chunk may appear at different addresses within the address spaces of different

user processes. </p> </li>

</ul> </section>

<section id="GUID-8E371955-C475-5980-A04F-B33EAADE1B1B"><title>Local and global

chunks</title> <p><b>Local chunks </b> </p> <p>A chunk is local when it is private to the process

creating it and is not intended for access by other user processes. </p> <p>A

local chunk cannot be mapped into any other process and is, therefore, used

for memory that does not need to be shared. </p> <p>A local chunk does not

have a name. </p> <p><b>Global chunks </b> </p> <p>A chunk is global if it is intended to be accessed

by other processes. </p> <p>Global chunks have names that can be used to identify

the chunk to another process wishing to access it. A process can open a global

chunk by name; this maps the chunk into that process's address space, allowing

direct access and enabling the sharing of data between processes. </p> <p>If

the name of the global chunk to be opened is known, use <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita#GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07/GUID-A6557BEE-D545-362E-AD00-A23DC64D5CEE"><apiname>RChunk::OpenGlobal()</apiname></xref>.

If a part of the name is known, use the <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita#GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07/GUID-BE5915FF-4C43-30D8-A6E3-45C33973CD9D"><apiname>RChunk::Open()</apiname></xref> variant

that takes a <xref href="GUID-DA41F070-0E54-3F8A-B301-39A0C6AFAB38.dita"><apiname>TFindChunk</apiname></xref>. </p> <p>A process can only access

an unnamed global chunk if it is passed a handle to that chunk from another

process. See <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita#GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07/GUID-BE5915FF-4C43-30D8-A6E3-45C33973CD9D"><apiname>RChunk::Open()</apiname></xref>. </p> </section>