|
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-0C8318B1-71D7-5384-97EB-85CBBC3E6B84" xml:lang="en"><title>IIC SHAI Implementation Layer: Master Channel</title><shortdesc>This document explains how to implement the a master channel |
|
13 in the SHAI implementation layer of IIC. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-38D02829-2B52-4E2E-ABD0-D88D5F1B5FBC"><title>Purpose</title> <p>This document explains how to implement a master channel on the |
|
15 SHAI implementation layer of IIC. </p> <p><b>Intended Audience</b> </p> <p>Base porting engineers. </p> <p><b>Introduction</b> </p> <p>IIC buses (a term used in this document to represent serial inter-chip |
|
16 buses that IIC can operate on) are a class of bus used to transmit |
|
17 non time-critical data between components of a hardware system. </p> </section> |
|
18 <section id="GUID-69ED3F3A-8D85-4940-B9C7-691081EC5E93"><title>Implementing |
|
19 a master channel</title> <p>You should read and understand the template |
|
20 port at<filepath> \os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic\iic_master</filepath> as this will provide most of the information you need to implement |
|
21 the master channel.</p><p>To implement the SHAI implementation layer |
|
22 of an IIC channel as master you must write a class extending <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. You must implement certain pure virtual |
|
23 functions of the parent class in the subclass. Those functions and |
|
24 any other functions which you write in the subclass are called the |
|
25 SHAI implementation layer. The functions inherited from the parent |
|
26 class are called the Platform Independent Layer (PIL). </p> <p>The |
|
27 four functions you must implement are: </p> <ul> |
|
28 <li id="GUID-B49F1DAB-AB30-5C95-BFAF-93D8DC779371"><p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref> </p> </li> |
|
29 <li id="GUID-A402D653-D8D5-5031-A647-ED02B95B4857"><p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> </p> </li> |
|
30 <li id="GUID-AF3B74BE-9193-51CD-B7E4-E721F2CCDC98"><p> <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref> </p> </li> |
|
31 <li id="GUID-242CB2B6-0DB0-53A0-B951-1FACA037DEE0"><p> <xref href="GUID-A5E66E7E-E03B-3249-A5E5-F0E5DFC3B3EB.dita"><apiname>CheckHdr()</apiname></xref> </p> </li> |
|
32 </ul> <p>You must also provide the following functionality: </p> <ul> |
|
33 <li id="GUID-7C3DDA6A-1976-518C-90D8-27BD1D2B9C23"><p>validation of |
|
34 input, </p> </li> |
|
35 <li id="GUID-6E61EE3F-D8A1-58B4-A129-61A42E710150"><p>interrupt service |
|
36 routines, and </p> </li> |
|
37 <li id="GUID-8018060E-C5D6-5C9C-BA63-05B9DAE47823"><p>reporting on |
|
38 transmission status using the callback function <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref> with the relevant error code. </p> </li> |
|
39 </ul> <p>Your implementation of the SHAI implementation layer will |
|
40 need to call functions of the PIL. You are restricted to using a certain |
|
41 subset of these. </p> <p><b>Implementing DoCreate()</b> </p> <p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref> is the second phase constructor of your class. |
|
42 Implement it to perform functionality including: </p> <ul> |
|
43 <li id="GUID-47401DEC-3072-541A-BE75-034E1ABFE40A"><p>call the PIL |
|
44 function <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>, </p> </li> |
|
45 <li id="GUID-C41E4C4B-10CE-5393-9326-83110FEBB244"><p>create the DFC |
|
46 queue for the driver and assign it to the driver by calling <xref href="GUID-391B9E13-9A66-3DD4-872F-439C46022448.dita"><apiname>SetDfcQueue()</apiname></xref>, </p> </li> |
|
47 <li id="GUID-D2E8E3FB-EF15-5257-BDD8-BA72D80EA129"><p>initialize the |
|
48 hardware, setting up interrupts, and </p> </li> |
|
49 <li id="GUID-851D395C-330B-5492-AD1A-A54A484ED63D"><p>initialize the |
|
50 other data structures representing the channel. </p> </li> |
|
51 </ul> <p><b>Implementing DoRequest()</b> </p> <p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> is the gateway function to the SHAI implementation layer. It configures |
|
52 the interface using the supplied configuration and processes transactions. |
|
53 It takes one argument <xref href="GUID-2803075B-3B59-3DF1-BB22-A6DF4DB6AA58.dita"><apiname>aTransaction</apiname></xref>, a pointer to |
|
54 a <xref href="GUID-1A326AA6-7C9F-3E61-9B55-34FCE771EB96.dita"><apiname>TIicBusTransaction</apiname></xref> object created by the client: |
|
55 you use the protected data functions of the PIL (listed below) to |
|
56 extract the data needed to perform the associated transfers. Implement <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> with functionality including the following: </p> <ul> |
|
57 <li id="GUID-A7E758C2-89C0-5CCE-A5D2-1F7019CDF890"><p>Extract the |
|
58 transaction parameters, that is the transaction header and transfers |
|
59 (<xref href="GUID-73FDF24F-0B9D-3A97-B9BB-E021257E77F1.dita"><apiname>TIicBusTransfer</apiname></xref>), </p> </li> |
|
60 <li id="GUID-EF3B0B5A-E03B-58FF-8E8B-90EB6C7F5CFF"><p>configure the |
|
61 interface with the configuration supplied in the transaction header, </p> </li> |
|
62 <li id="GUID-A38796B7-A3F3-50D0-86DC-CCB4D3C69658"><p>set up the hardware |
|
63 to start the first transfer, that is </p> <ul> |
|
64 <li id="GUID-94CAE80B-2221-5664-85FB-B06666851DDB"><p>extract the |
|
65 first transfer for one direction by calling <xref href="GUID-2ADBFCF5-109F-33BA-97D1-44DA7D8604F2.dita"><apiname>GetTransHalfDuplexTransfer()</apiname></xref>, </p> </li> |
|
66 <li id="GUID-4613E372-DA10-5105-816F-1890A4314CDD"><p>and if the transfer |
|
67 is full duplex extract the first transfer for the second direction |
|
68 by calling <xref href="GUID-0C7ACFD8-279D-385D-8BF4-B870ABD185CE.dita"><apiname>GetTransFullDuplexTransferPtr()</apiname></xref>, </p> </li> |
|
69 </ul> <p>in each case filling hardware FIFO buffers, enabling interrupts |
|
70 and so on, </p> </li> |
|
71 <li id="GUID-B3CF4DEE-DAA2-5ADD-BA08-9861C457AF35"><p>call the PIL |
|
72 function <xref href="GUID-967E4167-498F-3714-8CFB-8273968C551B.dita"><apiname>StartSlaveTimeoutTimer()</apiname></xref>, </p> </li> |
|
73 <li id="GUID-48D2A463-EB97-5604-8106-9980AAE0FFE6"><p>instruct the |
|
74 hardware to start transmission, and </p> </li> |
|
75 <li id="GUID-45785C69-E8FB-5548-B8FF-3EA3EE45447F"><p>return either |
|
76 an error code or <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> </li> |
|
77 </ul> <p>The effect of calling <codeph>DoRequest()</codeph> should |
|
78 be to start the sequence of transfers comprising the transaction. |
|
79 Typically, at the end of each transfer a hardware interrupt and associated |
|
80 DFC callback occurs. If the PIL function <codeph>StartSlaveTimeout()</codeph> was called to monitor the duration of an individual transfer, the |
|
81 PIL function <codeph>CancelTimeout()</codeph> should be called to |
|
82 cancel the timer. If the transfer was successful and a call to get |
|
83 the next transfers succeeds, the next transfer is set up. This continues |
|
84 until either all the transfers have been processed, or there is an |
|
85 error; after that, the PIL method <codeph>DIicBusChannelMaster::CompleteRequest()</codeph> is called to indicate the result. </p> <p><b>Implementing HandleSlaveTimeout()</b> </p> <p>If the timer started by the PIL method <codeph>StartSlaveTimeoutTimer()</codeph> expires then the slave peripheral has not responded within the expected |
|
86 time, and in such case some SHAI implementation layer-specific recovery |
|
87 will be required; this is to be provided by the implementation of |
|
88 <codeph>HandleSlaveTimeout()</codeph>. Implement it with functionality |
|
89 including: </p> <ul> |
|
90 <li id="GUID-37E4C87F-4980-5651-BD13-2AD8622A8F52"><p>stop the transmission, </p> </li> |
|
91 <li id="GUID-667655D7-76B0-5F0A-BFA5-F74B964AF982"><p>disable the |
|
92 hardware, and </p> </li> |
|
93 <li id="GUID-DCF7198C-BFB2-58EF-9014-C9BEB31F57E4"><p>call the PIL |
|
94 function <codeph>CompleteRequest()</codeph> with the <xref href="GUID-BAC2386E-8168-3CDB-9F9F-180319EF6920.dita"><apiname>KErrTimedOut</apiname></xref> error code. </p> </li> |
|
95 </ul> <p><b>Implementing CheckHdr()</b> </p> <p>Implement <xref href="GUID-B44147A7-D880-3510-A3F1-D73E9B5F8230.dita"><apiname>CheckHdr().</apiname></xref> This is the function which is called in the |
|
96 context of the client thread when the client calls <xref href="GUID-D0F8DF19-790F-3FE5-89E4-057C240AD3FE.dita"><apiname>QueueTransaction()</apiname></xref>. Implement it with the following functionality: </p> <ul> |
|
97 <li id="GUID-42548EF0-4A41-5095-8541-CDC8BF6032D4"><p>check if the |
|
98 header of the transaction is valid. </p> </li> |
|
99 </ul> <p><b>Using the Platform Independent Layer</b> </p> <p>You can |
|
100 only use certain functions of the PIL. Most are used to access private |
|
101 data of the parent class. Others provide functionality which is generic |
|
102 to IIC buses. These are: </p> <ul> |
|
103 <li id="GUID-1034BC57-BC77-5D7F-9385-3ACCC0EFF6DE"><p> <xref href="GUID-995FA70D-F28C-3AA6-BB6A-528210F3716E.dita"><apiname>DIicBusChannelMaster()</apiname></xref>, the constructor of the superclass <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref> with arguments representing the bus type and the duplex settings. </p> </li> |
|
104 <li id="GUID-27AE6A8A-3C0E-5DC3-917B-0F23D3D6E7C2"><p> <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>. Initializes <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. </p> </li> |
|
105 <li><p>•<codeph>SetDfcQ()</codeph>. Sets the driver's DFC queue to |
|
106 be used by DFCs in the PIL. </p></li> |
|
107 <li id="GUID-B90804B6-0A44-5764-B6AD-62F0A0E0C8C5"><p> <xref href="GUID-30953225-638A-3627-8183-544E127FE72C.dita"><apiname>StartSlaveTimeOutTimer()</apiname></xref>. Starts a timer which causes the <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref> callback to run if the transaction (or transfer, SHAI implementation |
|
108 layer decides) is not completed in the specified time. </p> </li> |
|
109 <li id="GUID-4AC4BD6D-2123-5151-B744-8785A4D4E364"><p> <xref href="GUID-03DA2EEC-8E8C-30FC-9956-E721184FE43E.dita"><apiname>CancelTimeOut();</apiname></xref>. Cancels the timeout timer which monitors the transaction time. </p> </li> |
|
110 <li id="GUID-B61C0B7E-43EF-55E6-9BA6-9791F3858D76"><p> <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref>. Called to signal the PIL about completed transactions, transmission |
|
111 errors and timeouts. </p> </li> |
|
112 </ul> <p>The functions accessing private members of <xref href="GUID-1A326AA6-7C9F-3E61-9B55-34FCE771EB96.dita"><apiname>TIicBusTransaction</apiname></xref> are: </p> <table id="GUID-11F852E6-4180-5F2D-BC57-5F45946C9F71"> |
|
113 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
114 <thead> |
|
115 <row> |
|
116 <entry>Function</entry> |
|
117 <entry>Returns</entry> |
|
118 </row> |
|
119 </thead> |
|
120 <tbody> |
|
121 <row> |
|
122 <entry><p> <codeph>GetTransactionHeader() </codeph> </p> </entry> |
|
123 <entry><p>A pointer to the configuration header. </p> </entry> |
|
124 </row> |
|
125 <row> |
|
126 <entry><p> <codeph>GetTransHalfDuplexTfrPtr()</codeph> </p> </entry> |
|
127 <entry><p>A pointer to the head of the list of half duplex transfers. </p> </entry> |
|
128 </row> |
|
129 <row> |
|
130 <entry><p> <codeph>GetTransFullDuplexTfrPtr()</codeph> </p> </entry> |
|
131 <entry><p>A pointer to the head of the list of full duplex transfers. </p> </entry> |
|
132 </row> |
|
133 <row> |
|
134 <entry><p><codeph>GetTransCallback()</codeph></p></entry> |
|
135 <entry><p>A pointer to the callback function</p></entry> |
|
136 </row> |
|
137 <row> |
|
138 <entry><p><codeph>GetTransFlags()</codeph></p></entry> |
|
139 <entry><p>a pointer to the transaction flags</p></entry> |
|
140 </row> |
|
141 </tbody> |
|
142 </tgroup> |
|
143 </table> <p>The functions accessing private members of <xref href="GUID-73FDF24F-0B9D-3A97-B9BB-E021257E77F1.dita"><apiname>TIicBusTransfer</apiname></xref> are: </p> <table id="GUID-6B66FB92-634F-5B57-8AEE-7D90606BF26F"> |
|
144 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
145 <thead> |
|
146 <row> |
|
147 <entry>Function</entry> |
|
148 <entry>Returns</entry> |
|
149 </row> |
|
150 </thead> |
|
151 <tbody> |
|
152 <row> |
|
153 <entry><p> <xref href="GUID-779C14B5-7D9D-3582-BE22-21CB668FADE6.dita"><apiname>GetTferType()</apiname></xref> </p> </entry> |
|
154 <entry><p>The transfer type, EMasterRead or <xref href="GUID-5E76AC81-4074-337D-86E4-B3FC14062B51.dita"><apiname>EMasterWrite</apiname></xref>, defined in the enumeration <xref href="GUID-5FBF20DE-E998-3281-A85E-EF56A1FDDFA3.dita"><apiname>TReqType</apiname></xref>. </p> </entry> |
|
155 </row> |
|
156 <row> |
|
157 <entry><p> <xref href="GUID-D55D721A-4F5C-3B94-9351-971269E94493.dita"><apiname>GetTferBufGranularity()</apiname></xref> </p> </entry> |
|
158 <entry><p>The size of the buffer item in bits, typically 8 or 16. </p> </entry> |
|
159 </row> |
|
160 <row> |
|
161 <entry><p> <xref href="GUID-8A2E8454-957C-3F24-AF23-CF375C30EB05.dita"><apiname>GetTferBuffer()</apiname></xref> </p> </entry> |
|
162 <entry><p>A pointer to the buffer where the data is stored. </p> </entry> |
|
163 </row> |
|
164 <row> |
|
165 <entry><p> <xref href="GUID-FD0F5059-1B2B-3477-907C-9BC50D6CF6AE.dita"><apiname>GetTferNextTfer()</apiname></xref> </p> </entry> |
|
166 <entry><p>A pointer to the next transfer in the transaction. </p> </entry> |
|
167 </row> |
|
168 </tbody> |
|
169 </tgroup> |
|
170 </table><note>In addition to the above functions, there are additional |
|
171 functions for accessing transactions with preambles, extending transactions |
|
172 (multitransactions) and extended transactions with preamble. Refer |
|
173 to the header file for details on these functions.</note> </section> |
|
174 </conbody><related-links> |
|
175 <link href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita"><linktext>IIC |
|
176 SHAI Implementation Layer: Generic Considerations</linktext></link> |
|
177 <link href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita"><linktext>IIC |
|
178 SHAI implementation Layer: Slave Channel</linktext></link> |
|
179 <link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client |
|
180 of Master Channel Tutorial</linktext></link> |
|
181 <link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client |
|
182 of Slave Channel Tutorial</linktext></link> |
|
183 <link href="GUID-B2F86F54-EF50-56DB-ADF7-15325AC9324D.dita"><linktext>IIC |
|
184 Concepts</linktext></link> |
|
185 <link href="GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita"><linktext>I2C |
|
186 Technology Guide</linktext></link> |
|
187 </related-links></concept> |