<?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-18C39927-625C-5B24-919F-469FCBCD501D" xml:lang="en"><title>BCA2

API Overview</title><shortdesc>Explains the second Baseband Channel Abstraction design (BCA2). </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-8EA6D7A7-26A8-5B96-ADD7-E01E86B05329"><title>Required background</title> <p>You

should be familiar with the following areas: </p> <ul>

<li id="GUID-CCE01846-276A-5EB9-9876-DBBC90BD31A7"><p>architecture of device

drivers in Symbian platform (see <xref href="GUID-8D80AA51-5108-5D4B-B6B9-7FA47570AB89.dita">Device

Drivers Concepts</xref>) </p> </li>

<li id="GUID-8DAA8E32-B216-5279-A4AE-4435596F5517"><p>general principles of

a telephony stack (see <xref href="GUID-FA5A24BE-F4AF-5EC3-8969-6184A5A5BBFA.dita">Cellular

Baseband Services</xref>) </p> </li>

<li id="GUID-01DF1F36-5E88-5365-82E3-6601FBFE5F48"><p>networking and telephony

components. </p> </li>

</ul> </section>

<section id="GUID-679587F9-CD73-51C2-8D7E-AE5817533660"><title>Key concepts

and terms</title> <p> </p> <dl>

<dlentry>

<dt>BCA</dt>

<dd><p>Baseband Channel Adapter </p> </dd>

</dlentry>

<dlentry>

<dt>LDD</dt>

<dd><p>Logical device driver (see <xref href="GUID-8D80AA51-5108-5D4B-B6B9-7FA47570AB89.dita">Device

Drivers Concepts</xref>) </p> </dd>

</dlentry>

<dlentry>

<dt>PPP</dt>

<dd><p>Point-to-Point Protocol (see <xref href="GUID-E18F402A-6478-5B24-8DC0-33989FC5FD43.dita">What

is PPP?</xref>) </p> </dd>

</dlentry>

<dlentry>

<dt>HDLC</dt>

<dd><p>High-level Data Link Control </p> </dd>

</dlentry>

<dlentry>

<dt>ISDN</dt>

<dd><p>Integrated Services Digital Network </p> </dd>

</dlentry>

<dlentry>

<dt>ECUART</dt>

<dd><p>Serial RS232 driver for Symbian OS. UART means Universal Asynchronous

Receiver/Transmitter. </p> </dd>

</dlentry>

<dlentry>

<dt>C32</dt>

<dd><p>Serial Communications Server in Symbian OS (see <xref href="GUID-9B83CDD4-FC94-51A0-AC67-CD04BCAFEF08.dita">Serial

Communications Server</xref>) </p> </dd>

</dlentry>

</dl> </section>

<section id="GUID-FEB0738E-8AB9-48DD-8648-493AC70258A0"><title>Introduction</title> <p>The Baseband Channel Adapter (BCA)

provides a telephony-specific abstraction of the baseband driver. </p> <p>You

implement your BCA components depending on the level of abstraction you require,

providing a standard interface to the component above it in the Communications

stack. You can also stack BCA components for more flexibility. </p> <p>Performance

is a critical requirement for the Comms Data Plane. To improve throughput,

update your BCA components and your link layer protocol plugins to use the <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MBca2</apiname></xref> interface. </p> </section>

<section id="GUID-5D32EEFF-FFF5-51DE-AF53-F182A4E49F9D"><title>Architecture</title> <p>This

topic focuses on a general case where there is one BCA component between the

driver and the lower layer of the Data Plane. In the case of a stack of BCA

components, the same design is repeated between each BCA layer. </p> <p>In

a "pull" communication model, the destination requests data from the source.

Data transfer happens when the destination is ready. In a "push" model, the

source provides data to the destination : data transfer happens when the source

is ready. </p> <p>BCA2 is based on a "push" architecture. The link layer component

registers with the BCA component. The BCA component provides the data to its

registered clients as soon as the data becomes available. </p> <p>The API

is split into five classes to separate control flow and data flow methods. </p> <fig id="GUID-699CB340-3DBB-50F5-8555-D4E2609BDECC">

<title>              MBca2 design            </title>

<image href="GUID-0B45D491-F88A-5036-A51C-9BFD6DB574D5_d0e62608_href.png" placement="inline"/>

</fig> <p>Moreover, the <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MBca2</apiname></xref> interface

relies on shared buffers instead of regular buffers. Using shared buffers

avoids data copies between different layers of the stack. For more information,

see <xref href="GUID-A248C2C0-5F64-5484-85B2-57C86E3499E1.dita">Memory Management

in the Communications Framework</xref>. </p> </section>

<section id="GUID-5826984F-EAFA-5EDC-9C39-3966C89373A2"><title>APIs</title> <p><b>BCA component</b> </p> <table id="GUID-049AA111-6F8D-52F3-9681-0746FD0E4E9B">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MBca2</apiname></xref>  </p> </entry>

<entry><p>Provides startup and shutdown methods. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MLowerDataSender</apiname></xref>  </p> </entry>

<entry><p>Provides the <codeph>Send()</codeph> method, which takes a <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>RCommsBufChain</apiname></xref> as its parameter

and is called by the link layer component whenever it needs to send data to

the baseband (through the BCA component). </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MLowerControl</apiname></xref>  </p> </entry>

<entry><p>Provides methods for downwards flow control and control options.

The control options depend on your implementations of the BCA, the driver

and the link layer component. For examples of control options, see the <xref href="GUID-E054E7F6-3918-5F76-8489-D5CFC9EE257A.dita">BCA2 Control Options</xref> reference

page. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Link

layer component</b> </p> <table id="GUID-D33F08E6-3192-56C8-9989-82B82F7024AC">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MUpperDataReceiver</apiname></xref>  </p> </entry>

<entry><p>Provides the <codeph>Process()</codeph> method, which takes a <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>RCommsBufChain</apiname></xref> as its parameter

and is called by the lower BCA component whenever data is available, in order

to push the data to the upper layer. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-55442FD0-FD97-3FA3-A61A-C1288C4D5670.dita"><apiname>MUpperDataControl</apiname></xref>  </p> </entry>

<entry><p>Provides methods for error management and upwards flow control. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>In the case of stacked BCA components, these APIs are implemented

by the upper BCA component. </p> </section>

<section id="GUID-71B6234B-470C-5241-A899-679709B91AE0"><title>Typical uses</title> <p>Device

driver developers implement the BCA2 design in the Networking stack (BCA components

and link layer protocol plugins). </p> <p>The following three diagrams show

common BCA components and illustrate how they integrate with the Communications

Framework. For definition of the abbreviations used in the diagrams, see the <xref href="GUID-18C39927-625C-5B24-919F-469FCBCD501D.dita#GUID-18C39927-625C-5B24-919F-469FCBCD501D/GUID-679587F9-CD73-51C2-8D7E-AE5817533660">Key

concepts and terms</xref> section. </p> <fig id="GUID-4B18CDAD-FDF3-5AF2-8B7C-85DC77C3E5FE">

<title>              Use case for BCA: IP communication through the serial

port            </title>

<image href="GUID-0F5C8DA1-EF91-588B-A917-350793DA03A5_d0e62806_href.png" placement="inline"/>

</fig> <fig id="GUID-1297D10A-59C2-5C15-877D-7CF94B667878">

<title>              Use case for BCA: PPP communication through the serial

port            </title>

<image href="GUID-760222AA-59F0-58E6-A494-F9CB6D739960_d0e62814_href.png" placement="inline"/>

</fig> <fig id="GUID-4A636F57-AF70-5646-A957-4B4F4AD5EA70">

<title>              Use case for BCA: PPP communication over Ethernet   

        </title>

<image href="GUID-96F5CB06-F1C2-5F37-B5B8-DA8C086B73AA_d0e62822_href.png" placement="inline"/>

</fig> </section>

</conbody><related-links>

<link href="GUID-E054E7F6-3918-5F76-8489-D5CFC9EE257A.dita"><linktext>BCA2 Control

Options</linktext></link>