<?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-388004AF-6F99-4BBB-A8E0-D75DC5B6790C" xml:lang="en"><title>Test

Application</title><shortdesc>This document describes a simple application which is used to load

a device driver and test its functionality.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-F3E3C80E-D74B-4846-A614-B69D653130CA">       <title>Testing

device drivers</title>       <p>Drivers, apart from kernel extensions, are

not automatically started by the Kernel, so they must be explicitly loaded

by application. </p> <p>When testing an LDD-PDD model driver, it is a general

practice to write a simple test application that loads the LDD and PDD by

name, opens a logical channel, and calls the driver API to test the driver's

functionality. </p> <p>The following shows a command line test application

that does this: </p> <codeblock id="GUID-59C1DE97-3018-5B58-AF11-72A1F44B4C0F" xml:space="preserve">/** E32Main - Application, exe main entry point. */

GLDEF_C TInt E32Main()

    {

    ...

    // Load the PDD. This user API will load the PDD DLL by name 

    // and also enable the loader to search for the PDD object 

    // by name.

    r = User::LoadPhysicalDevice(KExDriverPdd);

    // PDD loading is considered successful, if either it is 

    // loaded now or it is already loaded.

    test((r==KErrNone)||(r==KErrAlreadyExists));

    // Load the LDD. This user API loads the LDD DLL by name 

    // and also enable the loader to search for the LDD object 

    // by name.

    r = User::LoadLogicalDevice(KExDriverLdd);

    // LDD loading is considered successful, if either it is 

    // loaded now or it is already loaded.

    test((r==KErrNone)||(r==KErrAlreadyExists));

    ...

    // Get device capabilities

    ...

    // Open the device with reference to the driver name.    

    r = device.Open(KDriverName);

    if (r==KErrNone)

        {

        ... // do required operations

        // Close the device. This handle is required only to 

        // get any device related information from the LDD factory 

        // object.

        device.Close();

        }

    // RExDriverChannel is an RBusLogicalChannel derived class, which provides a user side 

    // handle to a logical channel. It defines the driver interface.

    RExDriverChannel ldd;

    // Open the logical channel to the driver for unit 1. This is a 

    // user-side wrapper function for the    

    // RBusLogicalChannel::DoCreate() API. DoCreate() is 

    // called in Open() for unit 1.

    //

    r = ldd.Open(KUnit1);

    test(r==KErrNone);

    // Call the driver API using the RExDriverChannel interface and 

    // test for the functionality

    ...

    // Close the logical channel

    ldd.Close();

    // Free the logical device / LDD

    r=User::FreeLogicalDevice (KDriverName);

    test(r==KErrNone);

    // Instead of directly using the PDD name, get the PDD 

    // factory object name and append the extension name, to 

    // unload the PDD.

    TName pddName(KDriverName);

    _LIT(KVariantExtension, ".pdd");

    pddName.Append(KVariantExtension);

    // Free the PDD, resulting in freeing the PDD factory object   

    r=User::FreePhysicalDevice (pddName);

    test(r==KErrNone);

    ...

    }</codeblock> <p>If the driver is a kernel extension, then the Kernel

loads the driver when it boots, so an application does not need to load the

driver explicitly. Applications simply open a channel to the driver and call

the driver API as required. </p> <p>The <xref href="GUID-D16A6778-660E-302A-A3B5-DD98A088B7EC.dita"><apiname>RTest</apiname></xref> class provides

macros and functions that can be used in test applications. It provides macros

to validate a return value against an expected value, and to leave giving

the line number where the error occurred. It also provides macros to print

debug messages, to group the test sets, and so on. </p> <codeblock id="GUID-EB34D6B4-D9AC-5F47-BBEA-DBB04BBB5DEF" xml:space="preserve">// Create RTest object (test framework)

LOCAL_D RTest test(_L("Tutorial Driver"));

GLDEF_C TInt E32Main()

    {

    // Initialize the test object with a title    

    test.Title();

    // RTest::Starts() starts a set of tests

    test.Start(_L("Load Physical Device"));

    ...

    // RTest::Next() starts a new set of tests

    test.Next(_L("Open Channel"));

    ...

    // Test if a condition is true. If not, the application leaves 

    // displaying the line number and error type

    test(r==KErrNone)

    ...

    // Prints a string to the screen

    test.Printf(_L(“<display string %d>”),r);

    ...

    // End the tests     

    test.End();

    }</codeblock> <p>The drivers developed and built can be tested on the

target hardware. The debug or release versions of the driver are built into

the ROM and downloaded to the target. This is done either by using a MMC card,

USB, Serial or JTAG interface, as supported by the particular hardware board.

Once the board is powered on or reset, Symbian platform boots and the text

shell is displayed (assuming a text shell ROM image). To test an LDD-PDD driver,

run the test application from the command line. </p> <p>If debug messages

are enabled in the driver, by using <codeph>KTRACE</codeph> or <codeph>BTRACE</codeph>,

the messages can be viewed on the LCD screen, or through a connected COM port,

using the HyperTerminal application on a PC. </p>     </section>