Test Application

Testing device drivers

Drivers, apart from kernel extensions, are not automatically started by the Kernel, so they must be explicitly loaded by application.

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.

The following shows a command line test application that does this:

/** 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);

    ...
    }

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.

The RTest 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.

// 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();
    }

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.

If debug messages are enabled in the driver, by using KTRACE or BTRACE, the messages can be viewed on the LCD screen, or through a connected COM port, using the HyperTerminal application on a PC.