--- a/Symbian3/PDK/Source/GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,310 +1,310 @@
-<?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-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF" xml:lang="en"><title>Important
-Changes between EKA1 and Kernel Architecture 2</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>This document is a summary of the important changes made between EKA2 and
-the Kernel Architecture 2. </p>
-<ul>
-<li id="GUID-39A4F67F-15DD-5443-AF04-B51E659AD158"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-1F882F2F-3BF4-5891-824D-01144652A771">Real time kernel</xref> </p> </li>
-<li id="GUID-703989BD-22DD-5B48-BD44-03A6BCDE4B96"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-93FC5632-139C-529C-81BF-723D2931E422">Multi-threaded kernel</xref> </p> </li>
-<li id="GUID-B8B0160F-9762-5CB2-BB0E-F363E89F6DB5"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-58061C31-3D55-5C92-86A6-9A07748DE12D">Memory model</xref> </p> </li>
-<li id="GUID-E5C26246-2536-5092-B241-49BC0D7639F4"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-AEB5D074-7993-5ECE-8168-FFD7C7119842">Bootstrap</xref> </p> </li>
-<li id="GUID-77CB12E7-B1AA-5B94-AACE-E616289BAC09"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-858E4DFA-3988-566B-9B9C-614D7D64843D">Chunks per process</xref> </p> </li>
-<li id="GUID-45E655B9-11E5-5790-AA7D-BEA5A57ADC44"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-4F31E633-3418-5FEF-B034-E4E42D12ECAE">Releasing blocked threads</xref> </p> </li>
-<li id="GUID-8DC829A6-ECF3-5DA6-A212-C47242B7CF2E"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-86BE8113-3442-585D-8AA1-622C6A0E5C33">Stricter checking on the use of invalid handles</xref> </p> </li>
-<li id="GUID-21898C1A-9AF1-5A6A-B151-2446D8B26210"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-70A788E3-EDB4-52B5-85F1-083F0C041161">Kernel is no longer dependent on EUSER.DLL</xref> </p> </li>
-<li id="GUID-1915EE78-FBCC-5B1A-BA16-84FF781331D1"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-14A08FAE-ADA1-55A8-9398-309E7FE517E3">Kernel-side code no longer leaves</xref> </p> </li>
-<li id="GUID-7372DD68-A1E0-552B-B83E-6469586F4369"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-BCDC2615-0F4A-55A2-8806-0963C2939349">No kernel-Side support for unicode</xref> </p> </li>
-<li id="GUID-9D2D33C4-B3E1-5169-B10C-229318C69D9F"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-AA9A48C6-5033-5459-AC1A-809FAEFB9001">Kernel-side code uses DBase instead of CBase</xref> </p> </li>
-<li id="GUID-080AD2D2-2394-5653-89E8-3ADA0FB9AA38"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-745A19A0-FA97-5250-B493-C0613EAE162E">Asynchronous deletion</xref> </p> </li>
-<li id="GUID-125A5C43-0D8C-5CEB-99F0-2FBF80C466FD"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-EBD2C3D9-D422-5EDC-B2DF-BEBE713DFF49">Accessing user side memory directly not permitted</xref> </p> </li>
-<li id="GUID-42EA847A-CC94-5630-BC52-FF2A33DD0D39"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-E0313A56-3F85-5614-964A-30972BA0193D">Kernel side code uses DObject instead of CObject</xref> </p> </li>
-<li id="GUID-B16C285F-58CF-543A-91DA-42E12738D70F"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-FADA0E2F-A37B-58A1-93AD-5DEF04ECD0D1">Device Driver Model</xref> </p> </li>
-<li id="GUID-4E25E221-01D6-5F68-A205-2D03EF837DC4"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-66C87C5D-D71B-5D98-9B49-C7FD4D18D540">Base porting</xref> </p> </li>
-<li id="GUID-B02F4ACE-2139-588B-AEF4-14773B16EDF3"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-FA2341A0-1743-5FE3-9C22-E2575816BE8D">Emulator</xref> </p> </li>
-<li id="GUID-35FE60FE-0C63-5CC1-BC50-85B050265ADB"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-B3073835-E9D7-5219-BC63-D7296ABB9B5C">Kernel-side messages</xref> </p> </li>
-<li id="GUID-8C1A6D8D-23C7-5A80-A915-0938FC129F28"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita">Environment
-Slots</xref> </p> </li>
-<li id="GUID-A125477D-24BD-5C59-96FA-52C8448A8286"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-8D788A9A-3AE1-5A5E-9761-5DCC81A60603">Power management</xref> </p> </li>
-<li id="GUID-6A2B9214-A194-5819-A0FA-EC7B6E060563"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-E8321E95-FEE1-516D-8EED-30B6C2C25E18">Support for alternative heap allocators</xref> </p> </li>
-</ul>
-<section id="GUID-1F882F2F-3BF4-5891-824D-01144652A771"><title>Real time kernel</title> <p>One
-of the main design goals for EKA2 is to provide real-time guarantees for a
-subset of kernel operations. Real time performance is one that guarantees
-a response time; it does not mean that the response time is necessarily fast,
-it means that the time taken is bounded, i.e. it is deterministic or predictable. </p> <p>Very
-few changes to user side code are needed; the aim has been to maintain compatibility
-at the EUSER level as far as possible. Device drivers, however, will need
-some changes at the EUSER level, and more so on the kernel side. See the <xref href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita">Device Driver Guide</xref> for
-details. </p> </section>
-<section id="GUID-93FC5632-139C-529C-81BF-723D2931E422"><title> Multi-threaded
-kernel</title> <p>In EKA2, the kernel is multi-threaded, i.e. any number of
-threads can now run on the kernel side. This means that a lower priority kernel
-thread can be preempted by a higher priority thread. </p> <p>Each user thread
-has two stacks: a user stack as in EKA1, and an additional kernel stack allowing
-it to be preempted virtually anywhere while executing kernel-side code. This
-adds approximately 4k to each thread's memory requirements. </p> <p>This change
-has the effect of simplifying device driver design. It also means that most
-kernel-side data structures need to be protected against concurrent accesses
-to prevent race conditions. Several synchronisation primitives are available
-to achieve this. </p> <p>A deadlock prevention strategy must be followed by
-kernel-side code. </p> </section>
-<section id="GUID-58061C31-3D55-5C92-86A6-9A07748DE12D"><title>Memory model</title> <p>The
-EKA2 core kernel is MMU-agnostic. All MMU code is isolated into a “memory
-model”, which is linked at build time against the kernel. EKA2 provides three
-different memory models: </p> <ul>
-<li id="GUID-59368906-3EC3-52CF-A1B9-239ABAEB7F21"><p>Moving memory model:
-This is functionally equivalent to EKA1, and is intended for ARMv4 and ARMv5
-CPUs. A single page directory is used and page directory entries are moved
-between the home and run sections at address space switch time. </p> </li>
-<li id="GUID-D4FCDAB7-0D20-5122-86CC-CAAA5F551DF7"><p>Multiple memory model:
-This is a new model for CPUs based on ARMv6 architecture. There is one page
-directory per process </p> </li>
-<li id="GUID-BE4852CB-3C4C-59A0-807D-D8E6150635EB"><p>Single memory model:
-This model can be used for CPUs that have no MMU, or to simplify of porting
-the core kernel to a new MMU-aware CPU. In the latter case, the MMU is enabled
-but there is a single address space in the system. This allows incremental
-porting to a new CPU, by first porting the kernel and then the MMU. </p> </li>
-</ul> <p>The memory map (e.g. the base address of the ROM image) has changed.
-Therefore any code relying on the EKA1 memory map will need changing. The
-impact should be minimal, as code outside the kernel should not be making
-assumptions about memory layout. </p> </section>
-<section id="GUID-AEB5D074-7993-5ECE-8168-FFD7C7119842"><title>Bootstrap</title> <p>The
-C/C++ generic bootstrap used in EKA1 has been replaced with an assembler bootstrap,
-which is split into a generic layer usable on any ARM device and a device-specific
-layer. </p> </section>
-<section id="GUID-858E4DFA-3988-566B-9B9C-614D7D64843D"><title>Chunks per
-process</title> <p>The number of chunks per process is limited to 16 in the
-moving memory model. This ensures that switching between address spaces operates
-in bounded time. </p> </section>
-<section id="GUID-4F31E633-3418-5FEF-B034-E4E42D12ECAE"><title>Releasing blocked
-threads</title> <p>Threads that are blocked on semaphores and mutexes are
-now released in priority order, not in FIFO order. </p> </section>
-<section id="GUID-86BE8113-3442-585D-8AA1-622C6A0E5C33"><title>Stricter checking
-on the use of invalid handles</title> </section>
-<section id="GUID-70A788E3-EDB4-52B5-85F1-083F0C041161"><title>Kernel is no
-longer dependent on EUSER.DLL</title> <p>The kernel no longer has any dependency
-on EUSER.DLL. Only user side code can link against EUSER.DLL. </p> <p>There
-are three main reasons for this: </p> <ul>
-<li id="GUID-72571CC2-FFC1-56FF-8B64-C3AEF94F2581"><p>It allows more robust
-on-target application debugging, as it is no longer possible to crash the
-kernel by putting an application breakpoint in shared code. </p> </li>
-<li id="GUID-91726D13-397C-58E8-9405-185D05C13F0E"><p>It reduces the size
-of the minimum system configuration. </p> </li>
-<li id="GUID-61B6DEAD-42F4-5BBC-9A83-8C038149E114"><p>It allows the kernel
-to be built using a different compiler to that used to build the user side. </p> </li>
-</ul> <p>This has important consequences for kernel side code. Any code that
-runs on the kernel side, including device drivers, cannot use classes, functionality,
-or behaviour that is implemented by EUSER.DLL. Although not a complete replacement
-for this lost functionality, the Nanokernel and the Symbian platform kernel
-do provide a set of utility functions such as <xref href="GUID-E2C25A1E-46B4-3697-A939-613CA366D87A.dita"><apiname>memcpy()</apiname></xref>, <xref href="GUID-5A95E126-A82F-3F29-9810-FA1CD35E8B19.dita"><apiname>memset()</apiname></xref>,
-and <xref href="GUID-AC5005AE-EDC0-36EE-B877-2F91B09B0068.dita"><apiname>memmove()</apiname></xref>. </p> </section>
-<section id="GUID-14A08FAE-ADA1-55A8-9398-309E7FE517E3"><title>Kernel-side
-code no longer leaves</title> <p>Kernel-side code can no longer use the leave/cleanup
-stack mechanism. If appropriate, functions must now provide a return code,
-and callers need to check return values. </p> <p>Note that this mechanism
-is still available on the user side. </p> </section>
-<section id="GUID-BCDC2615-0F4A-55A2-8806-0963C2939349"><title>No kernel-Side
-support for unicode</title> <p>The EKA2 kernel only provides support for ASCII
-strings. </p> <p>All kernel objects such as processes, threads, etc. have
-ASCII names. The kernel does use a few unicode strings but it treats them
-as opaque types. As kernel object names are limited to ASCII, user-side code
-must use only the ASCII subset of unicode when creating such objects. </p> </section>
-<section id="GUID-AA9A48C6-5033-5459-AC1A-809FAEFB9001"><title>Kernel-side
-code uses DBase instead of CBase</title> <p>Classes that are instantiated
-on the kernel heap must now use <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> instead of <codeph>CBase</codeph>. <codeph>CBase</codeph> can
-only be used by user-side code. </p> <p> <codeph>DBase</codeph> is defined
-in <filepath>...\e32\include\kernel\klib.h</filepath> and exported to <filepath>\epoc32\include\kernel\klib.h</filepath> </p> </section>
-<section id="GUID-745A19A0-FA97-5250-B493-C0613EAE162E"><title>Asynchronous
-deletion</title> <p>The <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> class provides the behaviour
-that allows objects to be deleted asynchronously. This is particularly useful
-when memory deallocation needs to be done by time critical code. </p> <p>Deletion
-is done by placing the object onto a queue and then triggering a DFC, which
-runs in the context of the supervisor thread. </p> </section>
-<section id="GUID-EBD2C3D9-D422-5EDC-B2DF-BEBE713DFF49"><title>Accessing user
-side memory directly not permitted</title> <p>Kernel side code must not access
-user side memory directly. Use the functions specifically provided for the
-purpose: </p> <p> <xref href="GUID-B56A34CD-E5B5-3E3E-A2EE-3BC9D248B210.dita"><apiname>kumemget()</apiname></xref>, <xref href="GUID-15B62FF1-5D59-3A84-9648-EB0DBFE17232.dita"><apiname>kumemget32()</apiname></xref>, <xref href="GUID-C7AB0391-99D5-31A2-91D4-A7F195546FC3.dita"><apiname>kumemput()</apiname></xref>, <xref href="GUID-D141C3C4-F2F6-37DF-BDF6-63DDE9052FA0.dita"><apiname>kumemput32()</apiname></xref>, <xref href="GUID-B51F91FF-E5CD-3D5F-8BB3-B18E58761B62.dita"><apiname>kumemset()</apiname></xref>, <xref href="GUID-F5136CAF-B66F-388D-A610-D0153CAF7E23.dita"><apiname>umemget()</apiname></xref>, <xref href="GUID-B55573FC-B21C-384A-8B1E-A6A4301310E9.dita"><apiname>umemget32()</apiname></xref>, <xref href="GUID-371860F0-36BF-340D-BEF6-1763EF9874AE.dita"><apiname>umemput()</apiname></xref>, <xref href="GUID-B2DF3520-01CE-3D2C-8137-746ADBCBAE80.dita"><apiname>umemput32()</apiname></xref>, <xref href="GUID-16048974-7407-3778-9BD3-B8417E3F795A.dita"><apiname>umemset()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-C505206F-F54F-3760-BA7D-2DB52AB4E0B3"><apiname>Kern::ThreadDesRead()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-FA321582-6D75-37A1-8DAB-D50638F76593"><apiname>Kern::ThreadDesWrite()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-904A42A8-8077-3FC6-BEF2-29619F079842"><apiname>Kern::ThreadRawRead()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-182C88F4-326C-376E-9FBE-889E3CB9B68A"><apiname>Kern::ThreadRawWrite()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-D7CE1BF2-F1B8-30E9-9D34-7BDDA39C1B0C"><apiname>Kern::KUDesGet()</apiname></xref>,
-and <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-8B62DE20-357F-3499-9F2E-FAD4B18C34D6"><apiname>Kern::KUDesPut()</apiname></xref> </p> <p>See also <xref href="GUID-F46B87B7-97A9-530B-BAC4-EF1DB9C91E39.dita#GUID-F46B87B7-97A9-530B-BAC4-EF1DB9C91E39/GUID-4A7BCB91-C58B-597F-85B6-74463BE9BC04">accessing User Memory</xref> in <xref href="GUID-F46B87B7-97A9-530B-BAC4-EF1DB9C91E39.dita">Porting
-a device driver from EKA1 to EKA2</xref> </p> </section>
-<section id="GUID-E0313A56-3F85-5614-964A-30972BA0193D"><title>Kernel side
-code uses DObject instead of CObject</title> <p>Kernel side objects that are
-reference counting, must now derive from <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref> instead
-of <codeph>CObject</codeph>. </p> <p> <codeph>CObjectCon</codeph> also has
-a kernel-side equivalent <xref href="GUID-7FB9067F-D200-382C-84F7-49F0548D0A7F.dita"><apiname>DObjectCon</apiname></xref>. </p> </section>
-<section id="GUID-FADA0E2F-A37B-58A1-93AD-5DEF04ECD0D1"><title>Device Driver
-Model</title> <p>The device driver model has changed. See the <xref href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita">Device
-Driver Guide</xref> for the detail. </p> </section>
-<section id="GUID-66C87C5D-D71B-5D98-9B49-C7FD4D18D540"><title>Base porting</title> <p>EKA1,
-allows only a single hardware interfacing architecture. The lowest layer of
-the kernel contains the ASSP-specific code and a separate variant DLL contains
-variant-specific code called by the kernel. </p> <p>In contrast, the EKA2
-core kernel, <filepath>ekern.exe</filepath>, is agnostic as regards the hardware
-interfacing architecture. It does not contain any peripheral-related code,
-and and only requires a variant DLL. The amount of functionality to be provided
-by this DLL is much smaller than in EKA1. </p> <p>In general, EKA2 base ports
-use one of the following two architectures: </p> <ul>
-<li id="GUID-57765CBB-ED06-50FD-8A9D-A972BD1FD517"><p>ASSP+Variant: where
-the Variant is split into an ASSP layer (a DLL) and a Variant layer (a DLL).
-The first DLL contains all the ASSP-specific / device-agnostic code, and the
-second DLL contains the device-specific code. This allows code sharing between
-different devices using the same ASSP/ASIC. The interface between the ASSP
-and variant DLLs is private. </p> </li>
-<li id="GUID-F52159AE-5A0A-5452-A742-F212DF68D948"><p>Variant alone: Both
-the ASSP and the device specific code is included in a single Variant DLL.
-This saves the effort of partitioning the code if only one device is planned. </p> </li>
-</ul> <p>In addition, peripheral-related features that are part of the kernel
-in EKA1 (e.g. DMA framework) are now implemented as kernel extensions. </p> </section>
-<section id="GUID-FA2341A0-1743-5FE3-9C22-E2575816BE8D"><title>Emulator</title> <p>A
-number of changes in the emulator architecture have a system-wide impact. </p> <p><b>Process emulation</b> </p> <p>The emulator supports multiple Symbian platform
-processes. This removes the need for WINS-specific code in various places,
-notably in server start-up. </p> <p>The emulator still runs as a single WIN32
-process, so a Symbian platform process can still accidentally write into the
-address space of another Symbian platform process. </p> <p><b>Thread scheduling</b> </p> <p>The emulator uses the same scheduling algorithm
-as Symbian platform running on hardware. This is in contrast with EKA1 that
-leaves Symbian platform thread scheduling to the Windows kernel leading to
-discrepancies in behaviour between the emulator and hardware. </p> <p><b>Calling WIN32 APIs from Symbian OS code</b> </p> <p>Because the emulator
-now uses the same scheduling algorithm as native Symbian platform, the Symbian
-platform kernel may have to suspend a thread while it is executing some arbitrary
-code inside Windows. If the thread holds one or more (Windows) locks when
-it is suspended and another thread tries to acquire the same lock(s), a deadlock
-occurs. To prevent this, Symbian platform code that calls into the WIN32 API
-must use new Symbian platform APIs, <codeph>Emulator::Lock()/Unlock()</codeph> or <codeph>Emulator::Escape()/Reenter()</codeph>.
-The impact should be minimal because most of the code interacting with Windows
-is in the Base subsystem. </p> </section>
-<section id="GUID-B3073835-E9D7-5219-BC63-D7296ABB9B5C"><title>Kernel-side
-messages</title> <p>Because the kernel is multi-threaded in EKA2, <xref href="GUID-178E140F-BB15-5A82-99A6-D1BC0E11E018.dita">Kernel-side
-messages</xref> offer a means of communication between Symbian platform threads
-executing kernel-side code. Typically, they are used by device drivers to
-communicate between a client thread, usually a user thread, and a kernel thread
-running the actual device driver code. </p> </section>
-<section id="GUID-E897C3F8-F275-59F0-BBFC-7981865226F2"><title>Passing handles
-& data at process creation</title> <p>In EKA2, handles and binary data
-(in the form of descriptors, or integer values) can be passed to a process
-at process creation time. Up to 16 separate pieces of information can be passed
-to a process on creation. </p> <p>See <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita">Passing
-handles & data at process creation</xref> for more information. </p> </section>
-<section id="GUID-8D788A9A-3AE1-5A5E-9761-5DCC81A60603"><title>Power management</title> <p>The
-EKA1 power management framework has been replaced in EKA2 with a new framework
-that aims at fixing known issues with the EKA1 one. The main design goal for
-this new framework is increased flexibility, i.e.: </p> <ul>
-<li id="GUID-03A92EBE-669D-50C1-905B-AA7B9A3FC68A"><p>providing support for
-a wide variety of power management hardware </p> </li>
-<li id="GUID-FF1E50F6-6DE3-5919-A703-BDA5440E26A1"><p>separating mechanism
-and policy to allow different power management strategies. </p> </li>
-</ul> <p>As an example of increased flexibility, the set of supported power
-states is extensible by licensees. </p> <p>The changes mean that, on the user
-side, there is no binary or source compatibility. The impacted components
-are app-framework/UIKON and the GUI LAF (e.g. techview/toolkit). </p> <p>On
-the kernel-side, there is no binary compatibility. Old-style power handlers
-can still be built but if one or more of them are active, the system cannot
-switch to standby mode. </p> <p>In EKA2, the power model DLL no longer exists.
-EKA2 replaces the EKA1 user-side framework with a new one based on the concept
-of domain. A domain is a set of processes that share the same power management
-characteristics. </p> <p><b>User-side
-changes</b> </p> <p>A new user-side domain server manages all domains in the
-system and centralises interactions with the kernel. The main requests supported
-by this server are: </p> <ul>
-<li id="GUID-63B5CEED-7B05-5F19-A99F-BD51DD144E23"><p>Transition all processes
-in a given domain to a new power state. </p> </li>
-<li id="GUID-66E37108-73A4-5844-BA3C-5E2FC3C9E1EC"><p>Transition all domains
-to a new power state. </p> </li>
-</ul> <p>The set of all domains forms a tree. A request to transition a domain
-D to a new power state is cascaded down to its children first. D is then transitioned
-after all its children have themselves transitioned to the new state. </p> <p>The
-domain server is policy-agnostic. It links against a customisable DLL that
-provides the policy part. This DLL notably specifies the structure of the
-domain tree. Usage of the domain framework is optional. Licensees are free
-to replace it with another user-side scheme or to implement all their power
-management policy kernel-side. </p> <p><b>Kernel-side
-changes</b> </p> <p>The new kernel-side framework breaks down into the following
-items: </p> <ul>
-<li id="GUID-2E0FC695-8527-59C7-8F56-09C6E9A349FB"><p>A power manager, embedded
-in the core kernel, which implements the power management executive calls
-and manages the other kernel-side entities </p> </li>
-<li id="GUID-5A04F61E-499A-5CE5-B6EF-19FA26517D53"><p>A set of power handlers
-implemented within device drivers. When a power transition is requested, the
-power manager dispatches it to every registered power handler. </p> </li>
-<li id="GUID-5576AC0E-4CB6-544A-A547-674EBFC74513"><p>A power controller implemented
-in a kernel extension. It manages the different sleep modes supported by the
-CPU. </p> </li>
-</ul> <p>The power handlers and power controller are device-specific. A specific
-implementation could specify a private interface between these components
-to extend the generic framework. For example power handlers could notify the
-power controller of state changes so the latter can select the most appropriate
-sleep mode. </p> </section>
-<section id="GUID-E8321E95-FEE1-516D-8EED-30B6C2C25E18"><title> Support for
-alternative heap allocators</title> <p>User mode threads and processes can
-now instantiate their own concrete heap allocator classes for use as the default
-allocator rather than be required to use the Symbian platform supplied <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> class. </p> <p>This
-has been done by defining the new abstract class <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref>. <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>,
-now derives from this new class. </p> <p>The new class allows threads and
-processes to replace the standard first-fit heap allocator class to improve
-allocation performance or solve memory fragmentation problems. </p> <p>The
-change has been made to minimise binary compatibilty and source compatibility
-impact on existing software. The following standard allocation functions are
-completely compatible: </p> <ul>
-<li id="GUID-74113B2B-BA3B-57D8-B0E5-7CDB81E9B7A0"><p> <xref href="GUID-B89E4D10-0DFD-3270-B45B-565B01421466.dita"><apiname>operator new()</apiname></xref> </p> </li>
-<li id="GUID-400E98C4-04DC-5608-879B-579D487139DF"><p> <xref href="GUID-05782A1A-60BF-3D6F-AA78-8C1B25E1A3C8.dita"><apiname> operator
-delete()</apiname></xref> </p> </li>
-<li id="GUID-317BADC6-0FBB-56A8-9B88-705231ED74AC"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-67554CF1-F7D1-37E3-8088-1625B3FCEBB4"><apiname> User::Alloc()</apiname></xref> </p> </li>
-<li id="GUID-C1A56138-2D40-558D-9A00-221F911974EF"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-C035F07D-B6D9-3A21-A323-DAC89137280D"><apiname> User::AllocL()</apiname></xref> </p> </li>
-<li id="GUID-0D584313-138F-5463-86B8-E5B558A5FE17"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-8944FF54-F874-3340-872B-CF6AD001F694"><apiname>User::AllocLC()</apiname></xref> </p> </li>
-<li id="GUID-84E0415D-66F4-5A61-818F-244790DAD52A"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A1B58B92-E9B2-3C0F-89B3-BA3230A1E14F"><apiname>User::Free()</apiname></xref> </p> </li>
-<li id="GUID-356C7BD2-81BC-59EB-A626-E7DD4E1698DC"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-076A396B-D9F1-3CB9-8D93-AF2E1D0C9415"><apiname>User::ReAlloc()</apiname></xref> </p> </li>
-<li id="GUID-8C59C1D4-F248-5459-9AB8-B19E5F4316D5"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-7804ECCB-D061-3572-A4C4-A629098F0790"><apiname> User::ReAllocL()</apiname></xref> </p> </li>
-<li id="GUID-A9ABCC69-F7AD-589E-AA3A-B797757C7123"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-AE5D927B-2CFB-3CE0-9EB7-437C4482241F"><apiname>User::AllocLen()</apiname></xref> </p> </li>
-<li id="GUID-A1D29CE1-8D07-5587-8FBF-F9B8903561D5"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-E970D052-A8D6-3430-9E23-EB935DD32335"><apiname> User::AllocSize()</apiname></xref> </p> </li>
-<li id="GUID-D5CDA68B-0172-5A80-99AB-69FFD8985975"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-62895F0B-089D-36F8-81C9-718B3D26585A"><apiname>User::Available()</apiname></xref> </p> </li>
-<li id="GUID-21AB331F-A559-5D6A-8C5A-C0B65CEAF76F"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-6755A02F-524F-3718-AD87-AE4A3BE20D3A"><apiname> User::CountAllocCells()</apiname></xref> </p> </li>
-<li id="GUID-16A3DA52-1513-525A-84B2-B63C85E73DFB"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-B2710076-A191-3F8B-B562-E92AE776549C"><apiname> User::FreeZ()</apiname></xref> </p> </li>
-<li id="GUID-7E64E012-BF78-5618-9B07-112A566E892E"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-82CD000F-BE5C-37EF-9B85-FC0A57570702"><apiname>User::Check()</apiname></xref> </p> </li>
-<li id="GUID-7CD596C5-657A-58D4-91DF-9DE72D5B9CE5"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-04A2474D-0A77-37A7-8567-BB7BC33C3CBE"><apiname> User::CompressAllHeaps()</apiname></xref> </p> </li>
-</ul> <p>The following functions are compatible assuming that the thread has
-not replaced the heap allocator with a different object: </p> <ul>
-<li id="GUID-7D68B874-0D5B-5432-8F9B-78CAA32B4036"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-E6BB60B3-B367-34EF-B843-3D32568275FF"><apiname>User::Adjust()</apiname></xref> </p> </li>
-<li id="GUID-D3324C8B-3FF1-58AA-86AB-C65CAFB7FA76"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-4DDE6BB9-F0D8-3A0F-8F70-03728E80E26C"><apiname>User::AdjustL()</apiname></xref> </p> </li>
-<li id="GUID-91DF8623-3DF2-5977-B097-FFC6953B7ACA"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-42AC433D-1C9C-3AC6-8640-EB1A7BA876B5"><apiname>User::Heap()</apiname></xref> </p> </li>
-<li id="GUID-D1895B52-9A53-598C-8B64-F97B1956992F"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-D157A678-62BB-3BF8-8166-C9E03F258E2A"><apiname> User::SwitchHeap()</apiname></xref> </p> </li>
-<li id="GUID-F1473064-A52E-511A-91AB-2FC51E01B705"><p> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-6FA3E28C-49D8-39CD-BFC7-FEAEADE40BA5"><apiname> RThread::Heap()</apiname></xref> </p> </li>
-<li id="GUID-B45BE2A4-944D-51F3-94FA-BC005C8195DD"><p> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-4A1F473A-A804-3984-AEED-B47ACA79AE49"><apiname> RThread::SetHeap()</apiname></xref> </p> </li>
-</ul> <p>The following functions have been added to support software that
-wishes to replace the heap allocator: </p> <ul>
-<li id="GUID-B0E30820-C1F2-5A70-8A04-33EA56ED3602"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-25730109-73AF-3F5A-83F5-EE5FB18A5692"><apiname> User::Allocator()</apiname></xref> </p> </li>
-<li id="GUID-3B23EB7D-D4D5-509A-827A-6853EC7578AE"><p> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-518DF5B4-3454-32B8-BC3F-F0D47274EF97"><apiname> RThread::Allocator()</apiname></xref> </p> </li>
-</ul> <p> <codeph>RThread::GetRamSizes()</codeph> is now deprecated – the
-heap size is always reported as zero, and the stack size should now be extracted
-using the new <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-699F8282-62EF-3F13-85DC-5C0F7910A43D"><apiname>RThread::StackInfo()</apiname></xref> API. </p> <p>Software
-that is dependent on the layout of the <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> internal data
-or virtual function table may no longer work after this change. Such software
-is likely to be rare or limited to test code. There is no legitimate dependency
-on this information except where 3rd party software has derived a class from
-RHeap, but this is considered to be very unlikely for anything other than
-test purposes. </p> <p>The default allocator object stored for each heap is
-no longer a <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>, but a <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref>.
-This means that it is possible that <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-42AC433D-1C9C-3AC6-8640-EB1A7BA876B5"><apiname>User::Heap()</apiname></xref> does not
-actually return a reference to a <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> object, possibly
-resulting in broken software. However, as the default class used for allocation
-is still <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>, then there is no additional impact unless
-a thread or process explicitly instantiates an alternative allocator class.
-In the latter case, we would expect that the code using the allocator to also
-be updated to use the alternative class. </p> <p>The allocator is created
-by the owning thread when it first runs, which means that software that depends
-on the heap existing before the thread is resumed will no longer work. In
-particular calling <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-6FA3E28C-49D8-39CD-BFC7-FEAEADE40BA5"><apiname>RThread::Heap()</apiname></xref> before the thread runs
-and creates the heap will return NULL. This was a real pattern found in several
-places in Symbian OS code to work around the lack of processes in the EKA1
-emulator, where a ‘command line’ is inserted into the created thread by allocating
-a cell on the new thread’s heap. This is not an issue for EKA2 as it supports
-processes in the emulator and such code should just be removed when adapting
-it for the EKA2 emulator. </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-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF" xml:lang="en"><title>Important
+Changes between EKA1 and Kernel Architecture 2</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This document is a summary of the important changes made between EKA2 and
+the Kernel Architecture 2. </p>
+<ul>
+<li id="GUID-39A4F67F-15DD-5443-AF04-B51E659AD158"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-1F882F2F-3BF4-5891-824D-01144652A771">Real time kernel</xref> </p> </li>
+<li id="GUID-703989BD-22DD-5B48-BD44-03A6BCDE4B96"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-93FC5632-139C-529C-81BF-723D2931E422">Multi-threaded kernel</xref> </p> </li>
+<li id="GUID-B8B0160F-9762-5CB2-BB0E-F363E89F6DB5"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-58061C31-3D55-5C92-86A6-9A07748DE12D">Memory model</xref> </p> </li>
+<li id="GUID-E5C26246-2536-5092-B241-49BC0D7639F4"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-AEB5D074-7993-5ECE-8168-FFD7C7119842">Bootstrap</xref> </p> </li>
+<li id="GUID-77CB12E7-B1AA-5B94-AACE-E616289BAC09"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-858E4DFA-3988-566B-9B9C-614D7D64843D">Chunks per process</xref> </p> </li>
+<li id="GUID-45E655B9-11E5-5790-AA7D-BEA5A57ADC44"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-4F31E633-3418-5FEF-B034-E4E42D12ECAE">Releasing blocked threads</xref> </p> </li>
+<li id="GUID-8DC829A6-ECF3-5DA6-A212-C47242B7CF2E"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-86BE8113-3442-585D-8AA1-622C6A0E5C33">Stricter checking on the use of invalid handles</xref> </p> </li>
+<li id="GUID-21898C1A-9AF1-5A6A-B151-2446D8B26210"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-70A788E3-EDB4-52B5-85F1-083F0C041161">Kernel is no longer dependent on EUSER.DLL</xref> </p> </li>
+<li id="GUID-1915EE78-FBCC-5B1A-BA16-84FF781331D1"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-14A08FAE-ADA1-55A8-9398-309E7FE517E3">Kernel-side code no longer leaves</xref> </p> </li>
+<li id="GUID-7372DD68-A1E0-552B-B83E-6469586F4369"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-BCDC2615-0F4A-55A2-8806-0963C2939349">No kernel-Side support for unicode</xref> </p> </li>
+<li id="GUID-9D2D33C4-B3E1-5169-B10C-229318C69D9F"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-AA9A48C6-5033-5459-AC1A-809FAEFB9001">Kernel-side code uses DBase instead of CBase</xref> </p> </li>
+<li id="GUID-080AD2D2-2394-5653-89E8-3ADA0FB9AA38"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-745A19A0-FA97-5250-B493-C0613EAE162E">Asynchronous deletion</xref> </p> </li>
+<li id="GUID-125A5C43-0D8C-5CEB-99F0-2FBF80C466FD"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-EBD2C3D9-D422-5EDC-B2DF-BEBE713DFF49">Accessing user side memory directly not permitted</xref> </p> </li>
+<li id="GUID-42EA847A-CC94-5630-BC52-FF2A33DD0D39"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-E0313A56-3F85-5614-964A-30972BA0193D">Kernel side code uses DObject instead of CObject</xref> </p> </li>
+<li id="GUID-B16C285F-58CF-543A-91DA-42E12738D70F"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-FADA0E2F-A37B-58A1-93AD-5DEF04ECD0D1">Device Driver Model</xref> </p> </li>
+<li id="GUID-4E25E221-01D6-5F68-A205-2D03EF837DC4"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-66C87C5D-D71B-5D98-9B49-C7FD4D18D540">Base porting</xref> </p> </li>
+<li id="GUID-B02F4ACE-2139-588B-AEF4-14773B16EDF3"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-FA2341A0-1743-5FE3-9C22-E2575816BE8D">Emulator</xref> </p> </li>
+<li id="GUID-35FE60FE-0C63-5CC1-BC50-85B050265ADB"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-B3073835-E9D7-5219-BC63-D7296ABB9B5C">Kernel-side messages</xref> </p> </li>
+<li id="GUID-8C1A6D8D-23C7-5A80-A915-0938FC129F28"><p> <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita">Environment
+Slots</xref> </p> </li>
+<li id="GUID-A125477D-24BD-5C59-96FA-52C8448A8286"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-8D788A9A-3AE1-5A5E-9761-5DCC81A60603">Power management</xref> </p> </li>
+<li id="GUID-6A2B9214-A194-5819-A0FA-EC7B6E060563"><p> <xref href="GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF.dita#GUID-43BC99CA-9D60-557C-A43C-99EF1D6E4ECF/GUID-E8321E95-FEE1-516D-8EED-30B6C2C25E18">Support for alternative heap allocators</xref> </p> </li>
+</ul>
+<section id="GUID-1F882F2F-3BF4-5891-824D-01144652A771"><title>Real time kernel</title> <p>One
+of the main design goals for EKA2 is to provide real-time guarantees for a
+subset of kernel operations. Real time performance is one that guarantees
+a response time; it does not mean that the response time is necessarily fast,
+it means that the time taken is bounded, i.e. it is deterministic or predictable. </p> <p>Very
+few changes to user side code are needed; the aim has been to maintain compatibility
+at the EUSER level as far as possible. Device drivers, however, will need
+some changes at the EUSER level, and more so on the kernel side. See the <xref href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita">Device Driver Guide</xref> for
+details. </p> </section>
+<section id="GUID-93FC5632-139C-529C-81BF-723D2931E422"><title> Multi-threaded
+kernel</title> <p>In EKA2, the kernel is multi-threaded, i.e. any number of
+threads can now run on the kernel side. This means that a lower priority kernel
+thread can be preempted by a higher priority thread. </p> <p>Each user thread
+has two stacks: a user stack as in EKA1, and an additional kernel stack allowing
+it to be preempted virtually anywhere while executing kernel-side code. This
+adds approximately 4k to each thread's memory requirements. </p> <p>This change
+has the effect of simplifying device driver design. It also means that most
+kernel-side data structures need to be protected against concurrent accesses
+to prevent race conditions. Several synchronisation primitives are available
+to achieve this. </p> <p>A deadlock prevention strategy must be followed by
+kernel-side code. </p> </section>
+<section id="GUID-58061C31-3D55-5C92-86A6-9A07748DE12D"><title>Memory model</title> <p>The
+EKA2 core kernel is MMU-agnostic. All MMU code is isolated into a “memory
+model”, which is linked at build time against the kernel. EKA2 provides three
+different memory models: </p> <ul>
+<li id="GUID-59368906-3EC3-52CF-A1B9-239ABAEB7F21"><p>Moving memory model:
+This is functionally equivalent to EKA1, and is intended for ARMv4 and ARMv5
+CPUs. A single page directory is used and page directory entries are moved
+between the home and run sections at address space switch time. </p> </li>
+<li id="GUID-D4FCDAB7-0D20-5122-86CC-CAAA5F551DF7"><p>Multiple memory model:
+This is a new model for CPUs based on ARMv6 architecture. There is one page
+directory per process </p> </li>
+<li id="GUID-BE4852CB-3C4C-59A0-807D-D8E6150635EB"><p>Single memory model:
+This model can be used for CPUs that have no MMU, or to simplify of porting
+the core kernel to a new MMU-aware CPU. In the latter case, the MMU is enabled
+but there is a single address space in the system. This allows incremental
+porting to a new CPU, by first porting the kernel and then the MMU. </p> </li>
+</ul> <p>The memory map (e.g. the base address of the ROM image) has changed.
+Therefore any code relying on the EKA1 memory map will need changing. The
+impact should be minimal, as code outside the kernel should not be making
+assumptions about memory layout. </p> </section>
+<section id="GUID-AEB5D074-7993-5ECE-8168-FFD7C7119842"><title>Bootstrap</title> <p>The
+C/C++ generic bootstrap used in EKA1 has been replaced with an assembler bootstrap,
+which is split into a generic layer usable on any ARM device and a device-specific
+layer. </p> </section>
+<section id="GUID-858E4DFA-3988-566B-9B9C-614D7D64843D"><title>Chunks per
+process</title> <p>The number of chunks per process is limited to 16 in the
+moving memory model. This ensures that switching between address spaces operates
+in bounded time. </p> </section>
+<section id="GUID-4F31E633-3418-5FEF-B034-E4E42D12ECAE"><title>Releasing blocked
+threads</title> <p>Threads that are blocked on semaphores and mutexes are
+now released in priority order, not in FIFO order. </p> </section>
+<section id="GUID-86BE8113-3442-585D-8AA1-622C6A0E5C33"><title>Stricter checking
+on the use of invalid handles</title> </section>
+<section id="GUID-70A788E3-EDB4-52B5-85F1-083F0C041161"><title>Kernel is no
+longer dependent on EUSER.DLL</title> <p>The kernel no longer has any dependency
+on EUSER.DLL. Only user side code can link against EUSER.DLL. </p> <p>There
+are three main reasons for this: </p> <ul>
+<li id="GUID-72571CC2-FFC1-56FF-8B64-C3AEF94F2581"><p>It allows more robust
+on-target application debugging, as it is no longer possible to crash the
+kernel by putting an application breakpoint in shared code. </p> </li>
+<li id="GUID-91726D13-397C-58E8-9405-185D05C13F0E"><p>It reduces the size
+of the minimum system configuration. </p> </li>
+<li id="GUID-61B6DEAD-42F4-5BBC-9A83-8C038149E114"><p>It allows the kernel
+to be built using a different compiler to that used to build the user side. </p> </li>
+</ul> <p>This has important consequences for kernel side code. Any code that
+runs on the kernel side, including device drivers, cannot use classes, functionality,
+or behaviour that is implemented by EUSER.DLL. Although not a complete replacement
+for this lost functionality, the Nanokernel and the Symbian platform kernel
+do provide a set of utility functions such as <xref href="GUID-E2C25A1E-46B4-3697-A939-613CA366D87A.dita"><apiname>memcpy()</apiname></xref>, <xref href="GUID-5A95E126-A82F-3F29-9810-FA1CD35E8B19.dita"><apiname>memset()</apiname></xref>,
+and <xref href="GUID-AC5005AE-EDC0-36EE-B877-2F91B09B0068.dita"><apiname>memmove()</apiname></xref>. </p> </section>
+<section id="GUID-14A08FAE-ADA1-55A8-9398-309E7FE517E3"><title>Kernel-side
+code no longer leaves</title> <p>Kernel-side code can no longer use the leave/cleanup
+stack mechanism. If appropriate, functions must now provide a return code,
+and callers need to check return values. </p> <p>Note that this mechanism
+is still available on the user side. </p> </section>
+<section id="GUID-BCDC2615-0F4A-55A2-8806-0963C2939349"><title>No kernel-Side
+support for unicode</title> <p>The EKA2 kernel only provides support for ASCII
+strings. </p> <p>All kernel objects such as processes, threads, etc. have
+ASCII names. The kernel does use a few unicode strings but it treats them
+as opaque types. As kernel object names are limited to ASCII, user-side code
+must use only the ASCII subset of unicode when creating such objects. </p> </section>
+<section id="GUID-AA9A48C6-5033-5459-AC1A-809FAEFB9001"><title>Kernel-side
+code uses DBase instead of CBase</title> <p>Classes that are instantiated
+on the kernel heap must now use <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> instead of <codeph>CBase</codeph>. <codeph>CBase</codeph> can
+only be used by user-side code. </p> <p> <codeph>DBase</codeph> is defined
+in <filepath>...\e32\include\kernel\klib.h</filepath> and exported to <filepath>\epoc32\include\kernel\klib.h</filepath> </p> </section>
+<section id="GUID-745A19A0-FA97-5250-B493-C0613EAE162E"><title>Asynchronous
+deletion</title> <p>The <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> class provides the behaviour
+that allows objects to be deleted asynchronously. This is particularly useful
+when memory deallocation needs to be done by time critical code. </p> <p>Deletion
+is done by placing the object onto a queue and then triggering a DFC, which
+runs in the context of the supervisor thread. </p> </section>
+<section id="GUID-EBD2C3D9-D422-5EDC-B2DF-BEBE713DFF49"><title>Accessing user
+side memory directly not permitted</title> <p>Kernel side code must not access
+user side memory directly. Use the functions specifically provided for the
+purpose: </p> <p> <xref href="GUID-B56A34CD-E5B5-3E3E-A2EE-3BC9D248B210.dita"><apiname>kumemget()</apiname></xref>, <xref href="GUID-15B62FF1-5D59-3A84-9648-EB0DBFE17232.dita"><apiname>kumemget32()</apiname></xref>, <xref href="GUID-C7AB0391-99D5-31A2-91D4-A7F195546FC3.dita"><apiname>kumemput()</apiname></xref>, <xref href="GUID-D141C3C4-F2F6-37DF-BDF6-63DDE9052FA0.dita"><apiname>kumemput32()</apiname></xref>, <xref href="GUID-B51F91FF-E5CD-3D5F-8BB3-B18E58761B62.dita"><apiname>kumemset()</apiname></xref>, <xref href="GUID-F5136CAF-B66F-388D-A610-D0153CAF7E23.dita"><apiname>umemget()</apiname></xref>, <xref href="GUID-B55573FC-B21C-384A-8B1E-A6A4301310E9.dita"><apiname>umemget32()</apiname></xref>, <xref href="GUID-371860F0-36BF-340D-BEF6-1763EF9874AE.dita"><apiname>umemput()</apiname></xref>, <xref href="GUID-B2DF3520-01CE-3D2C-8137-746ADBCBAE80.dita"><apiname>umemput32()</apiname></xref>, <xref href="GUID-16048974-7407-3778-9BD3-B8417E3F795A.dita"><apiname>umemset()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-C505206F-F54F-3760-BA7D-2DB52AB4E0B3"><apiname>Kern::ThreadDesRead()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-FA321582-6D75-37A1-8DAB-D50638F76593"><apiname>Kern::ThreadDesWrite()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-904A42A8-8077-3FC6-BEF2-29619F079842"><apiname>Kern::ThreadRawRead()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-182C88F4-326C-376E-9FBE-889E3CB9B68A"><apiname>Kern::ThreadRawWrite()</apiname></xref>, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-D7CE1BF2-F1B8-30E9-9D34-7BDDA39C1B0C"><apiname>Kern::KUDesGet()</apiname></xref>,
+and <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-8B62DE20-357F-3499-9F2E-FAD4B18C34D6"><apiname>Kern::KUDesPut()</apiname></xref> </p> <p>See also <xref href="GUID-F46B87B7-97A9-530B-BAC4-EF1DB9C91E39.dita#GUID-F46B87B7-97A9-530B-BAC4-EF1DB9C91E39/GUID-4A7BCB91-C58B-597F-85B6-74463BE9BC04">accessing User Memory</xref> in <xref href="GUID-F46B87B7-97A9-530B-BAC4-EF1DB9C91E39.dita">Porting
+a device driver from EKA1 to EKA2</xref> </p> </section>
+<section id="GUID-E0313A56-3F85-5614-964A-30972BA0193D"><title>Kernel side
+code uses DObject instead of CObject</title> <p>Kernel side objects that are
+reference counting, must now derive from <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref> instead
+of <codeph>CObject</codeph>. </p> <p> <codeph>CObjectCon</codeph> also has
+a kernel-side equivalent <xref href="GUID-7FB9067F-D200-382C-84F7-49F0548D0A7F.dita"><apiname>DObjectCon</apiname></xref>. </p> </section>
+<section id="GUID-FADA0E2F-A37B-58A1-93AD-5DEF04ECD0D1"><title>Device Driver
+Model</title> <p>The device driver model has changed. See the <xref href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita">Device
+Driver Guide</xref> for the detail. </p> </section>
+<section id="GUID-66C87C5D-D71B-5D98-9B49-C7FD4D18D540"><title>Base porting</title> <p>EKA1,
+allows only a single hardware interfacing architecture. The lowest layer of
+the kernel contains the ASSP-specific code and a separate variant DLL contains
+variant-specific code called by the kernel. </p> <p>In contrast, the EKA2
+core kernel, <filepath>ekern.exe</filepath>, is agnostic as regards the hardware
+interfacing architecture. It does not contain any peripheral-related code,
+and and only requires a variant DLL. The amount of functionality to be provided
+by this DLL is much smaller than in EKA1. </p> <p>In general, EKA2 base ports
+use one of the following two architectures: </p> <ul>
+<li id="GUID-57765CBB-ED06-50FD-8A9D-A972BD1FD517"><p>ASSP+Variant: where
+the Variant is split into an ASSP layer (a DLL) and a Variant layer (a DLL).
+The first DLL contains all the ASSP-specific / device-agnostic code, and the
+second DLL contains the device-specific code. This allows code sharing between
+different devices using the same ASSP/ASIC. The interface between the ASSP
+and variant DLLs is private. </p> </li>
+<li id="GUID-F52159AE-5A0A-5452-A742-F212DF68D948"><p>Variant alone: Both
+the ASSP and the device specific code is included in a single Variant DLL.
+This saves the effort of partitioning the code if only one device is planned. </p> </li>
+</ul> <p>In addition, peripheral-related features that are part of the kernel
+in EKA1 (e.g. DMA framework) are now implemented as kernel extensions. </p> </section>
+<section id="GUID-FA2341A0-1743-5FE3-9C22-E2575816BE8D"><title>Emulator</title> <p>A
+number of changes in the emulator architecture have a system-wide impact. </p> <p><b>Process emulation</b> </p> <p>The emulator supports multiple Symbian platform
+processes. This removes the need for WINS-specific code in various places,
+notably in server start-up. </p> <p>The emulator still runs as a single WIN32
+process, so a Symbian platform process can still accidentally write into the
+address space of another Symbian platform process. </p> <p><b>Thread scheduling</b> </p> <p>The emulator uses the same scheduling algorithm
+as Symbian platform running on hardware. This is in contrast with EKA1 that
+leaves Symbian platform thread scheduling to the Windows kernel leading to
+discrepancies in behaviour between the emulator and hardware. </p> <p><b>Calling WIN32 APIs from Symbian OS code</b> </p> <p>Because the emulator
+now uses the same scheduling algorithm as native Symbian platform, the Symbian
+platform kernel may have to suspend a thread while it is executing some arbitrary
+code inside Windows. If the thread holds one or more (Windows) locks when
+it is suspended and another thread tries to acquire the same lock(s), a deadlock
+occurs. To prevent this, Symbian platform code that calls into the WIN32 API
+must use new Symbian platform APIs, <codeph>Emulator::Lock()/Unlock()</codeph> or <codeph>Emulator::Escape()/Reenter()</codeph>.
+The impact should be minimal because most of the code interacting with Windows
+is in the Base subsystem. </p> </section>
+<section id="GUID-B3073835-E9D7-5219-BC63-D7296ABB9B5C"><title>Kernel-side
+messages</title> <p>Because the kernel is multi-threaded in EKA2, <xref href="GUID-178E140F-BB15-5A82-99A6-D1BC0E11E018.dita">Kernel-side
+messages</xref> offer a means of communication between Symbian platform threads
+executing kernel-side code. Typically, they are used by device drivers to
+communicate between a client thread, usually a user thread, and a kernel thread
+running the actual device driver code. </p> </section>
+<section id="GUID-E897C3F8-F275-59F0-BBFC-7981865226F2"><title>Passing handles
+& data at process creation</title> <p>In EKA2, handles and binary data
+(in the form of descriptors, or integer values) can be passed to a process
+at process creation time. Up to 16 separate pieces of information can be passed
+to a process on creation. </p> <p>See <xref href="GUID-AD2BD987-E097-5E1F-A914-B91CFB706D51.dita">Passing
+handles & data at process creation</xref> for more information. </p> </section>
+<section id="GUID-8D788A9A-3AE1-5A5E-9761-5DCC81A60603"><title>Power management</title> <p>The
+EKA1 power management framework has been replaced in EKA2 with a new framework
+that aims at fixing known issues with the EKA1 one. The main design goal for
+this new framework is increased flexibility, i.e.: </p> <ul>
+<li id="GUID-03A92EBE-669D-50C1-905B-AA7B9A3FC68A"><p>providing support for
+a wide variety of power management hardware </p> </li>
+<li id="GUID-FF1E50F6-6DE3-5919-A703-BDA5440E26A1"><p>separating mechanism
+and policy to allow different power management strategies. </p> </li>
+</ul> <p>As an example of increased flexibility, the set of supported power
+states is extensible by licensees. </p> <p>The changes mean that, on the user
+side, there is no binary or source compatibility. The impacted components
+are app-framework/UIKON and the GUI LAF (e.g. techview/toolkit). </p> <p>On
+the kernel-side, there is no binary compatibility. Old-style power handlers
+can still be built but if one or more of them are active, the system cannot
+switch to standby mode. </p> <p>In EKA2, the power model DLL no longer exists.
+EKA2 replaces the EKA1 user-side framework with a new one based on the concept
+of domain. A domain is a set of processes that share the same power management
+characteristics. </p> <p><b>User-side
+changes</b> </p> <p>A new user-side domain server manages all domains in the
+system and centralises interactions with the kernel. The main requests supported
+by this server are: </p> <ul>
+<li id="GUID-63B5CEED-7B05-5F19-A99F-BD51DD144E23"><p>Transition all processes
+in a given domain to a new power state. </p> </li>
+<li id="GUID-66E37108-73A4-5844-BA3C-5E2FC3C9E1EC"><p>Transition all domains
+to a new power state. </p> </li>
+</ul> <p>The set of all domains forms a tree. A request to transition a domain
+D to a new power state is cascaded down to its children first. D is then transitioned
+after all its children have themselves transitioned to the new state. </p> <p>The
+domain server is policy-agnostic. It links against a customisable DLL that
+provides the policy part. This DLL notably specifies the structure of the
+domain tree. Usage of the domain framework is optional. Licensees are free
+to replace it with another user-side scheme or to implement all their power
+management policy kernel-side. </p> <p><b>Kernel-side
+changes</b> </p> <p>The new kernel-side framework breaks down into the following
+items: </p> <ul>
+<li id="GUID-2E0FC695-8527-59C7-8F56-09C6E9A349FB"><p>A power manager, embedded
+in the core kernel, which implements the power management executive calls
+and manages the other kernel-side entities </p> </li>
+<li id="GUID-5A04F61E-499A-5CE5-B6EF-19FA26517D53"><p>A set of power handlers
+implemented within device drivers. When a power transition is requested, the
+power manager dispatches it to every registered power handler. </p> </li>
+<li id="GUID-5576AC0E-4CB6-544A-A547-674EBFC74513"><p>A power controller implemented
+in a kernel extension. It manages the different sleep modes supported by the
+CPU. </p> </li>
+</ul> <p>The power handlers and power controller are device-specific. A specific
+implementation could specify a private interface between these components
+to extend the generic framework. For example power handlers could notify the
+power controller of state changes so the latter can select the most appropriate
+sleep mode. </p> </section>
+<section id="GUID-E8321E95-FEE1-516D-8EED-30B6C2C25E18"><title> Support for
+alternative heap allocators</title> <p>User mode threads and processes can
+now instantiate their own concrete heap allocator classes for use as the default
+allocator rather than be required to use the Symbian platform supplied <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> class. </p> <p>This
+has been done by defining the new abstract class <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref>. <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>,
+now derives from this new class. </p> <p>The new class allows threads and
+processes to replace the standard first-fit heap allocator class to improve
+allocation performance or solve memory fragmentation problems. </p> <p>The
+change has been made to minimise binary compatibilty and source compatibility
+impact on existing software. The following standard allocation functions are
+completely compatible: </p> <ul>
+<li id="GUID-74113B2B-BA3B-57D8-B0E5-7CDB81E9B7A0"><p> <xref href="GUID-B89E4D10-0DFD-3270-B45B-565B01421466.dita"><apiname>operator new()</apiname></xref> </p> </li>
+<li id="GUID-400E98C4-04DC-5608-879B-579D487139DF"><p> <xref href="GUID-05782A1A-60BF-3D6F-AA78-8C1B25E1A3C8.dita"><apiname> operator
+delete()</apiname></xref> </p> </li>
+<li id="GUID-317BADC6-0FBB-56A8-9B88-705231ED74AC"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-67554CF1-F7D1-37E3-8088-1625B3FCEBB4"><apiname> User::Alloc()</apiname></xref> </p> </li>
+<li id="GUID-C1A56138-2D40-558D-9A00-221F911974EF"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-C035F07D-B6D9-3A21-A323-DAC89137280D"><apiname> User::AllocL()</apiname></xref> </p> </li>
+<li id="GUID-0D584313-138F-5463-86B8-E5B558A5FE17"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-8944FF54-F874-3340-872B-CF6AD001F694"><apiname>User::AllocLC()</apiname></xref> </p> </li>
+<li id="GUID-84E0415D-66F4-5A61-818F-244790DAD52A"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A1B58B92-E9B2-3C0F-89B3-BA3230A1E14F"><apiname>User::Free()</apiname></xref> </p> </li>
+<li id="GUID-356C7BD2-81BC-59EB-A626-E7DD4E1698DC"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-076A396B-D9F1-3CB9-8D93-AF2E1D0C9415"><apiname>User::ReAlloc()</apiname></xref> </p> </li>
+<li id="GUID-8C59C1D4-F248-5459-9AB8-B19E5F4316D5"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-7804ECCB-D061-3572-A4C4-A629098F0790"><apiname> User::ReAllocL()</apiname></xref> </p> </li>
+<li id="GUID-A9ABCC69-F7AD-589E-AA3A-B797757C7123"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-AE5D927B-2CFB-3CE0-9EB7-437C4482241F"><apiname>User::AllocLen()</apiname></xref> </p> </li>
+<li id="GUID-A1D29CE1-8D07-5587-8FBF-F9B8903561D5"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-E970D052-A8D6-3430-9E23-EB935DD32335"><apiname> User::AllocSize()</apiname></xref> </p> </li>
+<li id="GUID-D5CDA68B-0172-5A80-99AB-69FFD8985975"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-62895F0B-089D-36F8-81C9-718B3D26585A"><apiname>User::Available()</apiname></xref> </p> </li>
+<li id="GUID-21AB331F-A559-5D6A-8C5A-C0B65CEAF76F"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-6755A02F-524F-3718-AD87-AE4A3BE20D3A"><apiname> User::CountAllocCells()</apiname></xref> </p> </li>
+<li id="GUID-16A3DA52-1513-525A-84B2-B63C85E73DFB"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-B2710076-A191-3F8B-B562-E92AE776549C"><apiname> User::FreeZ()</apiname></xref> </p> </li>
+<li id="GUID-7E64E012-BF78-5618-9B07-112A566E892E"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-82CD000F-BE5C-37EF-9B85-FC0A57570702"><apiname>User::Check()</apiname></xref> </p> </li>
+<li id="GUID-7CD596C5-657A-58D4-91DF-9DE72D5B9CE5"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-04A2474D-0A77-37A7-8567-BB7BC33C3CBE"><apiname> User::CompressAllHeaps()</apiname></xref> </p> </li>
+</ul> <p>The following functions are compatible assuming that the thread has
+not replaced the heap allocator with a different object: </p> <ul>
+<li id="GUID-7D68B874-0D5B-5432-8F9B-78CAA32B4036"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-E6BB60B3-B367-34EF-B843-3D32568275FF"><apiname>User::Adjust()</apiname></xref> </p> </li>
+<li id="GUID-D3324C8B-3FF1-58AA-86AB-C65CAFB7FA76"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-4DDE6BB9-F0D8-3A0F-8F70-03728E80E26C"><apiname>User::AdjustL()</apiname></xref> </p> </li>
+<li id="GUID-91DF8623-3DF2-5977-B097-FFC6953B7ACA"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-42AC433D-1C9C-3AC6-8640-EB1A7BA876B5"><apiname>User::Heap()</apiname></xref> </p> </li>
+<li id="GUID-D1895B52-9A53-598C-8B64-F97B1956992F"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-D157A678-62BB-3BF8-8166-C9E03F258E2A"><apiname> User::SwitchHeap()</apiname></xref> </p> </li>
+<li id="GUID-F1473064-A52E-511A-91AB-2FC51E01B705"><p> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-6FA3E28C-49D8-39CD-BFC7-FEAEADE40BA5"><apiname> RThread::Heap()</apiname></xref> </p> </li>
+<li id="GUID-B45BE2A4-944D-51F3-94FA-BC005C8195DD"><p> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-4A1F473A-A804-3984-AEED-B47ACA79AE49"><apiname> RThread::SetHeap()</apiname></xref> </p> </li>
+</ul> <p>The following functions have been added to support software that
+wishes to replace the heap allocator: </p> <ul>
+<li id="GUID-B0E30820-C1F2-5A70-8A04-33EA56ED3602"><p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-25730109-73AF-3F5A-83F5-EE5FB18A5692"><apiname> User::Allocator()</apiname></xref> </p> </li>
+<li id="GUID-3B23EB7D-D4D5-509A-827A-6853EC7578AE"><p> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-518DF5B4-3454-32B8-BC3F-F0D47274EF97"><apiname> RThread::Allocator()</apiname></xref> </p> </li>
+</ul> <p> <codeph>RThread::GetRamSizes()</codeph> is now deprecated – the
+heap size is always reported as zero, and the stack size should now be extracted
+using the new <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-699F8282-62EF-3F13-85DC-5C0F7910A43D"><apiname>RThread::StackInfo()</apiname></xref> API. </p> <p>Software
+that is dependent on the layout of the <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> internal data
+or virtual function table may no longer work after this change. Such software
+is likely to be rare or limited to test code. There is no legitimate dependency
+on this information except where 3rd party software has derived a class from
+RHeap, but this is considered to be very unlikely for anything other than
+test purposes. </p> <p>The default allocator object stored for each heap is
+no longer a <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>, but a <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref>.
+This means that it is possible that <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-42AC433D-1C9C-3AC6-8640-EB1A7BA876B5"><apiname>User::Heap()</apiname></xref> does not
+actually return a reference to a <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> object, possibly
+resulting in broken software. However, as the default class used for allocation
+is still <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>, then there is no additional impact unless
+a thread or process explicitly instantiates an alternative allocator class.
+In the latter case, we would expect that the code using the allocator to also
+be updated to use the alternative class. </p> <p>The allocator is created
+by the owning thread when it first runs, which means that software that depends
+on the heap existing before the thread is resumed will no longer work. In
+particular calling <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-6FA3E28C-49D8-39CD-BFC7-FEAEADE40BA5"><apiname>RThread::Heap()</apiname></xref> before the thread runs
+and creates the heap will return NULL. This was a real pattern found in several
+places in Symbian OS code to work around the lack of processes in the EKA1
+emulator, where a ‘command line’ is inserted into the created thread by allocating
+a cell on the new thread’s heap. This is not an issue for EKA2 as it supports
+processes in the emulator and such code should just be removed when adapting
+it for the EKA2 emulator. </p> </section>
</conbody></concept>
\ No newline at end of file