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.