|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-388004AF-6F99-4BBB-A8E0-D75DC5B6790C" xml:lang="en"><title>Test |
|
13 Application</title><shortdesc>This document describes a simple application which is used to load |
|
14 a device driver and test its functionality.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-F3E3C80E-D74B-4846-A614-B69D653130CA"> <title>Testing |
|
16 device drivers</title> <p>Drivers, apart from kernel extensions, are |
|
17 not automatically started by the Kernel, so they must be explicitly loaded |
|
18 by application. </p> <p>When testing an LDD-PDD model driver, it is a general |
|
19 practice to write a simple test application that loads the LDD and PDD by |
|
20 name, opens a logical channel, and calls the driver API to test the driver's |
|
21 functionality. </p> <p>The following shows a command line test application |
|
22 that does this: </p> <codeblock id="GUID-59C1DE97-3018-5B58-AF11-72A1F44B4C0F" xml:space="preserve">/** E32Main - Application, exe main entry point. */ |
|
23 GLDEF_C TInt E32Main() |
|
24 { |
|
25 ... |
|
26 // Load the PDD. This user API will load the PDD DLL by name |
|
27 // and also enable the loader to search for the PDD object |
|
28 // by name. |
|
29 r = User::LoadPhysicalDevice(KExDriverPdd); |
|
30 |
|
31 // PDD loading is considered successful, if either it is |
|
32 // loaded now or it is already loaded. |
|
33 test((r==KErrNone)||(r==KErrAlreadyExists)); |
|
34 |
|
35 // Load the LDD. This user API loads the LDD DLL by name |
|
36 // and also enable the loader to search for the LDD object |
|
37 // by name. |
|
38 r = User::LoadLogicalDevice(KExDriverLdd); |
|
39 |
|
40 // LDD loading is considered successful, if either it is |
|
41 // loaded now or it is already loaded. |
|
42 test((r==KErrNone)||(r==KErrAlreadyExists)); |
|
43 ... |
|
44 |
|
45 // Get device capabilities |
|
46 ... |
|
47 |
|
48 // Open the device with reference to the driver name. |
|
49 r = device.Open(KDriverName); |
|
50 if (r==KErrNone) |
|
51 { |
|
52 ... // do required operations |
|
53 // Close the device. This handle is required only to |
|
54 // get any device related information from the LDD factory |
|
55 // object. |
|
56 device.Close(); |
|
57 } |
|
58 |
|
59 // RExDriverChannel is an RBusLogicalChannel derived class, which provides a user side |
|
60 // handle to a logical channel. It defines the driver interface. |
|
61 RExDriverChannel ldd; |
|
62 |
|
63 // Open the logical channel to the driver for unit 1. This is a |
|
64 // user-side wrapper function for the |
|
65 // RBusLogicalChannel::DoCreate() API. DoCreate() is |
|
66 // called in Open() for unit 1. |
|
67 // |
|
68 r = ldd.Open(KUnit1); |
|
69 test(r==KErrNone); |
|
70 |
|
71 // Call the driver API using the RExDriverChannel interface and |
|
72 // test for the functionality |
|
73 ... |
|
74 |
|
75 // Close the logical channel |
|
76 ldd.Close(); |
|
77 |
|
78 // Free the logical device / LDD |
|
79 r=User::FreeLogicalDevice (KDriverName); |
|
80 test(r==KErrNone); |
|
81 |
|
82 // Instead of directly using the PDD name, get the PDD |
|
83 // factory object name and append the extension name, to |
|
84 // unload the PDD. |
|
85 TName pddName(KDriverName); |
|
86 _LIT(KVariantExtension, ".pdd"); |
|
87 pddName.Append(KVariantExtension); |
|
88 |
|
89 // Free the PDD, resulting in freeing the PDD factory object |
|
90 r=User::FreePhysicalDevice (pddName); |
|
91 test(r==KErrNone); |
|
92 |
|
93 ... |
|
94 }</codeblock> <p>If the driver is a kernel extension, then the Kernel |
|
95 loads the driver when it boots, so an application does not need to load the |
|
96 driver explicitly. Applications simply open a channel to the driver and call |
|
97 the driver API as required. </p> <p>The <xref href="GUID-D16A6778-660E-302A-A3B5-DD98A088B7EC.dita"><apiname>RTest</apiname></xref> class provides |
|
98 macros and functions that can be used in test applications. It provides macros |
|
99 to validate a return value against an expected value, and to leave giving |
|
100 the line number where the error occurred. It also provides macros to print |
|
101 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) |
|
102 LOCAL_D RTest test(_L("Tutorial Driver")); |
|
103 |
|
104 GLDEF_C TInt E32Main() |
|
105 { |
|
106 // Initialize the test object with a title |
|
107 test.Title(); |
|
108 |
|
109 // RTest::Starts() starts a set of tests |
|
110 test.Start(_L("Load Physical Device")); |
|
111 ... |
|
112 // RTest::Next() starts a new set of tests |
|
113 test.Next(_L("Open Channel")); |
|
114 ... |
|
115 // Test if a condition is true. If not, the application leaves |
|
116 // displaying the line number and error type |
|
117 test(r==KErrNone) |
|
118 ... |
|
119 // Prints a string to the screen |
|
120 test.Printf(_L(“<display string %d>”),r); |
|
121 ... |
|
122 // End the tests |
|
123 test.End(); |
|
124 }</codeblock> <p>The drivers developed and built can be tested on the |
|
125 target hardware. The debug or release versions of the driver are built into |
|
126 the ROM and downloaded to the target. This is done either by using a MMC card, |
|
127 USB, Serial or JTAG interface, as supported by the particular hardware board. |
|
128 Once the board is powered on or reset, Symbian platform boots and the text |
|
129 shell is displayed (assuming a text shell ROM image). To test an LDD-PDD driver, |
|
130 run the test application from the command line. </p> <p>If debug messages |
|
131 are enabled in the driver, by using <codeph>KTRACE</codeph> or <codeph>BTRACE</codeph>, |
|
132 the messages can be viewed on the LCD screen, or through a connected COM port, |
|
133 using the HyperTerminal application on a PC. </p> </section> |
|
134 </conbody></concept> |