<?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>
</conbody></concept>