<?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 xml:lang="en" id="GUID-8F1567B4-6957-5B93-9499-35489AD610F5"><title>Chunks</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Chunks map RAM or memory-mapped I/O devices into contiguous virtual addresses. </p> <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 OS 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 OS 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"><image href="GUID-07F65EEA-5969-5E56-9570-245712FB3EE3_d0e332000_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"><image href="GUID-99C2E42F-1029-5E32-8446-CAAF29D733BA_d0e332011_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"><image href="GUID-59C143F6-3A0C-5C37-9351-A72FE45AFFC9_d0e332022_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 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>