|
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-D291C9E9-5207-4B23-B287-C240464087B9" xml:lang="en"><title>The |
|
13 PDD Entry Point and Factory</title><shortdesc>This document describes how PDDs are created.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-1099A347-6D77-4231-BAF5-B0EAAEA560B7"> <p>A PDD |
|
15 must define an entry point function using the macro <xref href="GUID-73947402-2F32-35C7-94C4-22B4D63D5FB3.dita"><apiname>DECLARE_STANDARD_PDD</apiname></xref>, |
|
16 or <xref href="GUID-52853C0D-CA98-3B92-B7D4-FF1C1F06C1A6.dita"><apiname>DECLARE_EXTENSION_PDD</apiname></xref> in the case of kernel extensions. |
|
17 This must create a PDD factory object derived from <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref>: </p><codeblock id="GUID-895AE2E1-A739-5FDB-8039-D382E7ACF245" xml:space="preserve">DECLARE_STANDARD_PDD() |
|
18 { |
|
19 return new DerivedPhysicalDevice; |
|
20 }</codeblock> <p>This factory object is created on the kernel heap. Its |
|
21 purpose is to create the physical channel, if needed. </p> <p> <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref> is |
|
22 derived from <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref>, and is, therefore a reference-counting |
|
23 object. It also means that <codeph>DPhysicalDevice</codeph> objects are given |
|
24 a name, as these objects are always subsequently found by name. Names are |
|
25 also used to identify those PDDs that can be used with a given LDD; they have |
|
26 a name of the form <codeph>x.y</codeph> where <codeph>x</codeph> is the name |
|
27 used by the LDD and <codeph>y</codeph> is PDD-specific. </p> <p>An LDD indicates |
|
28 that it requires an accompanying PDD by setting the LDD factory object member <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita#GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB/GUID-EB891156-94D9-323A-AB23-7B5994CD95E3"><apiname>DLogicalDevice::iParseMask</apiname></xref> with |
|
29 the <codeph>KDeviceAllowPhysicalDevice</codeph> flag. There are two ways that |
|
30 a suitable PDD can be found: </p> <ol id="GUID-FA526F7D-1DD7-5228-AA5C-CEBC74191B0B"> |
|
31 <li id="GUID-2D096381-32BD-57EB-9387-2B10B0020686"><p>A user can specify the |
|
32 name of a PDD through the <codeph>RBusLogicalChannel::DoCreate()</codeph> protected |
|
33 function: </p><codeblock id="GUID-21CE3362-AD93-5FCE-BBC7-212C919ED83C" xml:space="preserve">TInt DoCreate(const TDesC& aDevice, const TVersion& aVer, TInt aUnit, const TDesC* aDriver, const TDesC8* anInfo, TOwnerType aType=EOwnerProcess, TBool aProtected=EFalse);</codeblock> <p>The user side passes a pointer to a descriptor containing the name of |
|
34 the required PDD as the fourth argument. A PDD with that name must already |
|
35 have been loaded, and its factory object created. The device driver framework |
|
36 searches for a PDD factory object with that name, and if found, calls <codeph>Validate()</codeph> on |
|
37 that object; if this function returns <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>, then the |
|
38 PDD is accepted as the required PDD. </p> </li> |
|
39 <li id="GUID-ECF90DCF-71B6-5F1D-A3B5-0FF245A58306"><p>If no explicit PDD name |
|
40 is passed from the user side, then the device driver framework searches for |
|
41 all PDD factory objects, i.e. <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref> objects, |
|
42 that have a name in the form <codeph>x.y</codeph>, where <codeph>x</codeph> is |
|
43 the name of the LDD factory object. The device driver framework calls <codeph>Validate()</codeph> on |
|
44 each matching PDD factory object, passing the unit number and the optional |
|
45 extra information block; the first one to return <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> is |
|
46 accepted as the required PDD. </p> </li> |
|
47 </ol> <p>The file extension of a PDD DLL can be any permitted Symbian Platform |
|
48 name but, by convention, the PDD DLL has the extension <filepath>.PDD</filepath>. |
|
49 Device driver DLLs are polymorphic interface DLLs. When building PDDs, specify |
|
50 a target type of <i>pdd</i> in the <filepath>.mmp</filepath> file. </p> <p>A |
|
51 PDD is loaded by calling <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A0F4BF4A-9C58-3E5E-88E1-6D98597DDA18"><apiname>User::LoadPhysicalDevice()</apiname></xref>. This |
|
52 static function: </p><ul> |
|
53 <li id="GUID-EFB4CF23-26C3-5874-9709-5BE112F92C2A"><p>loads the DLL into RAM, |
|
54 if necessary </p> </li> |
|
55 <li id="GUID-4C131AE3-7048-5C91-9EF8-C7EBC04CC7B3"><p>calls the exported function |
|
56 at ordinal 1 to create the factory object, the <codeph>DPhysicalDevice</codeph> derived |
|
57 object </p> </li> |
|
58 <li id="GUID-FC279525-DC2E-5000-AE8F-B2E03F8A2FCF"><p>places the factory object |
|
59 into the appropriate object container. </p> </li> |
|
60 </ul> <note>This only needs to be done once, not every time the driver is |
|
61 used.</note><p>If a PDD needs to perform initialisation at boot time (before |
|
62 the driver is loaded by <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A0F4BF4A-9C58-3E5E-88E1-6D98597DDA18"><apiname>User::LoadPhysicalDevice()</apiname></xref>), then |
|
63 specify the entry point macros <codeph>DECLARE_STANDARD_EXTENSION</codeph> and <codeph>DECLARE_EXTENSION_PDD</codeph>. </p><codeblock id="GUID-CF83DB15-2040-5C18-9728-E1B3A56E9D50" xml:space="preserve">DECLARE_STANDARD_EXTENSION() |
|
64 { |
|
65 // initialise code here |
|
66 } |
|
67 |
|
68 DECLARE_EXTENSION_PDD() |
|
69 { |
|
70 return new DMyPhysicalFactory; |
|
71 }</codeblock> <note><p>In order for the kernel to initialise the PDD extension |
|
72 at boot time then the <filepath>.oby</filepath> file must specify the <codeph>extension</codeph> keyword. |
|
73 Also note that initialisation of the extension will not load the PDD - this |
|
74 still has to be done through a call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-67DF6521-DE70-39E1-8EFB-246D419F7566"><apiname>User::LoadPhysicalDevice().</apiname></xref></p></note> |
|
75 </section> |
|
76 </conbody></concept> |