<?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-6FEE5676-8BFB-53E6-A652-7178295C342E"><title>Pond Configuration Reference</title><shortdesc>This topic describes the file that configures the Comms pond. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-EB90011A-618E-5117-B0DC-961ECB723BA1">

<p>At the moment, there is only one pond in the Comms Frameowrk. This pond manages the pools of MBufs available to the device drivers and to the Comms Framework components. The pond is initialised by the Root Server when the device starts. For each pool, you specify the initial and maximum number of buffers and the size of these buffers by specifying options in the <filepath>c32start.ini</filepath> file. This file is located in <filepath>z\private\101f7988</filepath>. 

</p> 

</section> 

<section id="GUID-0F32ADF3-116E-50C6-9F28-445D11C8402E">

<title>Options</title> 

<p>To describe the pond, define <codeph>MBufSizeAllocInfo</codeph> <i>&lt;n&gt;</i> for each pool. </p> 

<p>Each <codeph>MBufSizeAllocInfo</codeph> <i>&lt;n&gt;</i> line describes a pool of RMBufs. The <i>&lt;n&gt;</i> suffix must be a unique number. </p> 

<codeblock id="GUID-766646D3-E426-5080-8721-0BDA63B66662" xml:space="preserve"># MBufSizeAllocInfo[n] = size, initial, growth, threshold

# for example 

MBufSizeAllocInfo1 = 128, 128, 64, 48 

MBufSizeAllocInfo2 = 1600, 64, 16, 12 </codeblock> 

<p>The following table lists the<codeph>MBufSizeAllocInfo</codeph> parameters in the order they must be specified: </p> 

<table id="GUID-258EAC07-2AA8-5195-8251-E5EDA097BB73">

<tgroup cols="3">

<colspec colname="col0"/>

<colspec colname="col1"/>

<colspec colname="col2"/>

<thead>

<row>

<entry>Parameter</entry> 

<entry>Unit</entry>

 <entry>Description</entry> 

 </row> 

 </thead> 

 <tbody>

 <row>

 <entry><p> <codeph>size</codeph>  </p> </entry> 

 <entry><p>bytes </p> </entry> 

 <entry><p>Size of the payload of the <codeph>RMBuf.</codeph>  </p> </entry> 

 </row> <row>

 <entry><p> <codeph>initial</codeph>  </p> </entry> 

 <entry><p>buffers </p> </entry> 

 <entry><p>Amount of pre-allocated <codeph>RMBuf</codeph> s in the pool at startup.  </p> </entry> 

 </row> <row>

 <entry><p> <codeph>growth</codeph>  </p> </entry> 

 <entry><p>buffers </p> </entry> 

 <entry><p>Amount of <codeph>RMBuf</codeph> s added to the pool when it grows. </p> </entry> 

 </row> <row>

 <entry><p> <codeph>threshold</codeph>  </p> </entry> 

 <entry><p>buffers </p> </entry> 

 <entry><p>Minimum amount of free <codeph>RMBuf</codeph> s before making the pool grow. When the amount of free buffers in the pool falls below the <codeph>threshold</codeph> value, the pond adds <codeph>growth</codeph> buffers to the pool. </p> </entry> 

 </row> 

 </tbody> 

 </tgroup> 

 </table> 

 <p>The initial allocation of memory is defined by the sum of the initial allocations from each of the <codeph>MBufSizeAllocInfo</codeph> <i>&lt;n&gt;</i> specifications. </p> 

 <p>If no <codeph>MBufSizeAllocInfo</codeph> <i>&lt;n&gt;</i> options are provided, the system builds a default pool of 128-byte buffers, initially set at 128 buffers, with a growth of 64 buffers and a threshold of 40 buffers. </p> 

 </section> 

 <section id="GUID-8F0E62BA-455A-5C58-9AB1-70C79F5BA573">

 <title>Recommendations</title> 

 <p>Growth thresholds are typically set at around 25% so that the background allocator can allocate new buffers before the current pool is exhausted. Systems where there is potential to use buffers in sudden bursts should set the threshold to a higher number or start with a larger initial number of buffers. </p> 

 <p>Legacy code may rely on 128-byte buffers. 128-byte buffers also work well as the small buffers used when adding headers to the data. You should always specify a pool of 128-byte buffers in your <codeph>c32start.ini</codeph> file. You should also avoid having a pool of buffers smaller than 128 bytes, because some legacy code may assume 128 bytes as the minimum size. </p> 

 <p>The Maximum Transmission Unit (MTU) is an important characteristic of Communications protocols. The MTU is the maximum size of the data packet in a given layer. For example, the Ethernet protocol fixes its MTU to 1,500 bytes, and the 802.11 protocol has a 2,272-bytes MTU. To ensure that incoming data can be written into a single buffer rather than split, you need to specify your pools according to the protocols in use in your system. For each of these protocols, the pond should contain a pool with buffers as large or larger than the MTU. Protocols with similar MTUs usually share the same pool, to avoid increasing the allocation time with searches through too many pools. </p> 

 <p>Increasing the number of pools increases the time required to fulfil an allocation request. Therefore, you should keep the number of pools small. You need to find a balance between searching many pools for a single adequate buffer and searching fewer pools but having to construct a chain of buffers to fulfil an allocation request. </p> 

 <p> <b>Note</b>: if the <codeph>c32start.ini</codeph> configuration specifies more memory than the device has available, or an impossible combination of initial pool sizes and total pond size, the pond initialisation will fail and the Root Server will panic during device start-up. </p> 

 </section> 

 <example id="GUID-E4D29345-47E1-549F-BEB0-C94E7DDFF00B">

 <title>Example</title> 

 <p>Here is a sample <filepath>c32start.ini</filepath> file: </p> 

 <codeblock id="GUID-2EE0270A-1892-552D-9D10-E19227069A73" xml:space="preserve">[Global]

MBufSizeAllocInfo1 = 128, 128, 64, 48

MBufSizeAllocInfo2 = 1600, 64, 16, 12</codeblock> 

<p>This file corresponds to the following configuration: </p> 

<ul id="UL_BA85BF6A92C7451CB25A8428AEBA90E3">

<li id="GUID-03BFDFCF-61CF-5BE9-A967-C4EFCD00C07F"><p>The pond contains two pools for a total of 128x128 + 64x1600 = 118,784 bytes (116kB). </p> </li> 

<li id="GUID-EB782141-97DD-509C-9EA0-507DFA8A8981"><p>The first pool contains 128-byte buffers. It starts with 128 buffers and will grow by 64 buffers whenever fewer than 48 free buffers remain. </p> </li> 

<li id="GUID-0D4FBD06-4F91-5393-A419-C5538D5FC2F1"><p>The second pool contains 1,600-byte buffers. It starts with 64 buffers and will grow by 16 buffers whenever fewer than 12 free buffers remain. </p> </li> 

</ul> 

</example> 

</conbody><related-links>

<link href="GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita"><linktext>Overview</linktext> </link> 

<link href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita"><linktext>Comms Buffers (MBuf) and Comms Chains</linktext> </link> 

<link href="GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita"><linktext>Advanced Pond Guide</linktext> </link> 

<link href="GUID-0995EBF6-D203-57B3-9F53-972AEB8F3D3C.dita"><linktext>Memory Metrics</linktext> </link>