<?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-B4F15CA3-CAD4-5A87-9610-A656CA337B72"><title>Comms Buffers (MBuf) ans Comms Chains</title><shortdesc>This topic describes Comms buffers (MBuf) and Comms chains. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-2290A2C1-C15B-5767-8BA5-0109457715AA"><title>APIs</title> <p>The following diagram is a partial representation of the class hierarchy for <codeph>RMBuf</codeph>. </p> <fig id="GUID-129D60A5-5FAB-52B1-BDD8-7B40F0038DD0"><title>

             Comms buffer 

          </title> <image href="GUID-4119C4BD-ABBF-524B-B649-0F39EF58A7FB_d0e142304_href.png" placement="inline"/></fig> <p>For more information about these classes, see the following table and the reference documentation: </p> <table id="GUID-BC77F10C-E6C7-5447-A61F-63671B5F0FEC"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Class</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-E0ADB108-D3B2-3670-907D-2AE595BECE3F.dita"><apiname>RMBuf</apiname></xref>  </p> </entry> <entry><p>Representation of a shared buffer designed to carry packets within the Comms Data Plane. </p> <p>It includes Comms metadata (such as the offset, the size and the type of the data within the buffer) and links to the next buffer in the buffer chain. </p> <p>Part of the API is located in the parent class : <xref href="GUID-4FB33BFE-DCF7-3B77-A447-F9C049DF86CB.dita"><apiname>RCommsBuf</apiname></xref>. </p> </entry> </row> <row><entry><p> <xref href="GUID-F024208C-ED19-3301-85C1-53F397C9910F.dita"><apiname>RMBufChain</apiname></xref>  </p> </entry> <entry><p>Chain of <codeph>RMBuf</codeph> objects. </p> <p>Part of the API is located in the parent class : <xref href="GUID-107ADE6D-7AFF-3B07-9606-BCA33A3B63EF.dita"><apiname>RCommsBufChain</apiname></xref>. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section id="GUID-5EBCD46C-5E07-5DB1-90D9-6A5CA3E36C0B"><title> Buffer layout</title> <p>The following diagram shows the contents of a Comms buffer and the location of the metadata. The metadata is at the end so that the device drivers can ignore the metadata and write their payload at the beginning of the buffer. </p> <fig id="GUID-6598A097-0453-5499-9507-2419DF73C023"><title>

             Comms buffer contents 

          </title> <image href="GUID-9FB3502C-B3DF-5FBC-972D-0D476D661954_d0e142391_href.png" placement="inline"/></fig> <p>The metadata contains information about the payload: its length and offset, the type of data it contains, and references to the pond and the pool where the buffer's memory is located. Whenever you perform an operation on an MBuf, the chain or the pond update the metadata. </p> <p>The offset at the beginning of the buffer is an important optimisation when sending data downwards through the Comms Data Plane. Leaving enough space for the protocol headers enables Comms Framework components to prepend their data to the payload without requesting a new MBuf and its addition to the front of the buffer chain. Therefore, you should always define a pool according to the biggest packet that the bottom of the stack may receive : for example, 1518 bytes for Ethernet packets. </p> <p>The following diagram is an example illustrating how the Comms Data Plane removes the headers from the payload (on the way up the stack) or prepend header to the payload (on the way down): </p> <fig id="GUID-17B63072-ED95-5626-88D0-80AF8790B5CE"><title>

             Header manipulation example 

          </title> <image href="GUID-32D39AB1-D1B0-5F44-8226-0777B8010C7D_d0e142406_href.png" placement="inline"/></fig> <p>For simplified code corresponding to this diagram, see <xref href="GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita">Data Access Example</xref>. </p> </section> </conbody><related-links><link href="GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita"><linktext>Overview</linktext> </link> <link href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita"><linktext>Shared Buffers</linktext> </link> <link href="GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita"><linktext>Advanced Pond