--- a/Symbian3/SDK/Source/GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,121 +1,121 @@
-<?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_d0e243804_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_d0e243820_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_d0e243836_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>
+<?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>
\ No newline at end of file