<?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-5C63EF5C-826D-5838-BB7E-12FF4EA1DFCE" xml:lang="en"><title>Debugging

the Host Controller</title><shortdesc>Describes how to debug the host controller.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The HCI extension-conduit enables the writing of vendor specific commands

to the Bluetooth host controller hardware via the stack. Specific debugging

events or command completions are received back through a "secure channel".

Event notifications are only available to the one client that issued the command

in the first place, and there is only one such client on a device at any one

time. </p>

<p><b>Intended Audience </b> </p>

<p>This document is intended to be read by Symbian platform licensees. </p>

<section id="GUID-19A5E2C9-4222-4759-BBBA-8A257313061C"><title>How to send vendor-specific debug commands to the host controller</title> <p>A

wrapper class <xref href="GUID-EEC833C9-8711-30FA-95B5-1FB8D7A02A0B.dita"><apiname>CHciExtensionConduit</apiname></xref> is provided to drive

a command/event loop on behalf of the client program. The wrapper class provides

callbacks into the client-implemented <xref href="GUID-2591274E-4F6F-315C-B170-82D980E82750.dita"><apiname>MVendorSpecificHciConduit</apiname></xref> interface

upon reception of a debug or command completion event. On construction, the <codeph>CHciExtensionConduit</codeph> registers

itself with the Bluetooth stack, which ensures that there can be only one

HCI Extension Conduit in existence on a machine at one time. This means that

the first such conduit constructed after bootup has sole access to issue vendor

specific commands and more importantly receive back vendor specific events. </p> <p><b>Basic Procedure</b> </p> <p>To send vendor specific debug commands to

the host controller: </p> <ol id="GUID-7C2C1742-54F1-533C-B511-4DB2486E6791">

<li id="GUID-2AB6F7B7-69BC-5DA2-A365-BC2E32B8DFE1"><p>create an array for

your vendor specific commands and a descriptor to hold this data </p> </li>

<li id="GUID-5567327D-A4EF-51AE-8123-3E358AF16CC7"><p>call <xref href="GUID-EEC833C9-8711-30FA-95B5-1FB8D7A02A0B.dita#GUID-EEC833C9-8711-30FA-95B5-1FB8D7A02A0B/GUID-1989D0A7-ADC4-33F2-B1B1-6F1DDB685DE1"><apiname>CHciExtensionConduit::IssueCommandL()</apiname></xref> to

issue the vendor specific command to the hardware, passing it the descriptor

containing the raw binary data for the command. The raw binary data should

not include the HCI transport header and footer bytes, as the stack will add

these automatically to the provided hex command. </p> </li>

<li id="GUID-2B1DD0BD-547B-5C66-BD73-2EA5406195CA"><p>define and implement <xref href="GUID-2591274E-4F6F-315C-B170-82D980E82750.dita#GUID-2591274E-4F6F-315C-B170-82D980E82750/GUID-08860F56-E933-3746-962F-92FA858EAB56"><apiname>MVendorSpecificHciConduit::CommandCompleted()</apiname></xref>:

this function is called when a vendor specific command issued through the

conduit receives a completion from the hardware. </p> </li>

<li id="GUID-0C35ABB8-E040-5DB9-85D4-62A8F7B71A2D"><p>If the command generates

debug events, call <xref href="GUID-EEC833C9-8711-30FA-95B5-1FB8D7A02A0B.dita#GUID-EEC833C9-8711-30FA-95B5-1FB8D7A02A0B/GUID-AB5A6279-CA79-3318-A3A1-111118985C57"><apiname>CHciExtensionConduit::WaitForEvent()</apiname></xref> to

instruct the conduit that vendor debug events are expected back from the hardware.

Implement <xref href="GUID-2591274E-4F6F-315C-B170-82D980E82750.dita#GUID-2591274E-4F6F-315C-B170-82D980E82750/GUID-C4154C63-3F48-3FF2-8702-923327370170"><apiname>MVendorSpecificHciConduit::ReceiveEvent()</apiname></xref> to

get your specific debug event data generated from the hardware. </p> </li>

</ol> <p><b> Example </b> </p> <codeblock id="GUID-1E719427-E3AB-5ED8-9EEC-C8C0D8EFE725" xml:space="preserve">class CDebugEventConsole : public CBase, private MVendorSpecificHciConduit

    {

public:

    static CDebugEventConsole* NewL();

 ~CDebugEventConsole();

private:

    ConstructL();

    CDebugEventConsole();

    virtual void CommandCompleted(TInt aError);

    virtual TBool ReceiveEvent(TDesC8& aEvent, TInt aError);

    CConsoleBase*            iConsole;

    CHciExtensionConduit*    iConduit;

    };

 CDebugEventConsole* CDebugEventConsole::NewL()

    {

    CDebugEventConsole* self=new (ELeave)CDebugEventConsole();

    CleanupStack::PushL(self);

    self->ConstructL();

    CleanupStack::Pop(self);

    return self;

    }

CDebugEventConsole::~CDebugEventConsole()

    {

    delete iConsole;

    delete iConduit;

    }

CDebugEventConsole::ConstructL()

    {

    TUint8 ActivateInfo[] = //returns response event and couple of extension events

        {

        0x01, 0x02, 0x03, 0x04, //example uses meaningless values, for illustration

        0x05, 0x06, 0x07, 0x08,

        0x09, 0x0A, 0x0B, 0x0C,

        0x0D, 0x0E, 0x0F, 0x10,

        0x11, 0x12, 0x13, 0x14,

        0x15, 0x16, 0x17, 0x18,

        0x19, 0x1A, 0x1B, 0x1C,

        0x1D, 0x1E, 0x1F, 0x20,

        0x21, 0x22, 0x23, 0x24,

        0x25, 0x26

        };

    ...

    TPtrC8 ExtensionCommand(ActivateInfo, sizeof(ActivateInfo));

    ...

    iConsole=Console::NewL(_L("listening for Events..."),TSize(20,20));

    iConduit = CHciExtensionConduit::NewL(*this);

    iConduit->IssueCommandL(ExtensionCommand);

    }

CDebugEventConsole::CDebugEventConsole()

    {

    }

void CDebugEventConsole::CommandCompleted(TInt aError)

    {

    iConsole->Printf(_L("Cmd Complt: %d\n"), aError);

        if(aError==KErrNone)

        {

        aError = iConduit->WaitForEvent();    

        iConsole->Printf(_L("WaitForEvent: %d\n"), aError);

        }

    }

TBool CDebugEventConsole::ReceiveEvent(TDesC8& aEvent, TInt aError)

    {

    iConsole->Printf(_L("Rcvd Event!\n  err %d Length %d\n"), aError, aEvent.Length());

    return ETrue; // Keep receiving events

    }

void DoEventListenerL()

    {

    CActiveScheduler *exampleScheduler = new (ELeave) CActiveScheduler();

    CleanupStack::PushL(exampleScheduler);

    CActiveScheduler::Install(exampleScheduler); 

    CleanupStack::PushL(CDebugEventConsole::NewL());

    CActiveScheduler::Start();

    CleanupStack::PopAndDestroy(2); // active shed, myDebug

    }

</codeblock> </section>

<section id="GUID-205EEED3-5B56-497C-9714-0D40653DABC5"><title>Where Next?</title> <p>This tutorial set takes you through

all the steps involved in setting up and communicating over a Bluetooth connection. </p> <ul>

<li id="GUID-710429DF-DDE9-5529-B0C5-62BE04E9FB03"><p> <xref href="GUID-70339E6A-63CD-5A74-846C-50771FDAC763.dita">Listening

for Incoming Bluetooth Connections</xref>  </p> </li>

<li id="GUID-40F5BDDB-06CF-5D2E-AD32-0BA5B9C2438F"><p> <xref href="GUID-834BD3BB-B39C-5EE9-8A62-9DC435930F95.dita">Handling

the Local Device Name</xref>  </p> </li>

<li id="GUID-E7C9448C-4C00-5755-BCF0-47ADD30F012C"><p> <xref href="GUID-FDA7B932-B9C6-502D-8699-C18C8D86BCC6.dita">Performing

Low-level Configuration</xref>  </p> </li>

<li id="GUID-8E85825C-92DB-554D-9EBC-74297A3CD148"><p> <b>Debugging the Host

Controller</b> - This document </p> </li>

<li id="GUID-39439F8A-81F6-5AA2-88D2-DEC3FCE8DC11"><p> <xref href="GUID-01A0682A-50B1-57AB-9939-6CC8FCCD782D.dita">Disconnecting

ACL links</xref>  </p> </li>

</ul> </section>

</conbody></concept>