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 Kernel-side

    13 Implementation Guide: Master Channel</title><shortdesc>This document explains how to implement an interface from Symbian

    14 platform to an IIC bus as a master channel. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <section id="GUID-38D02829-2B52-4E2E-ABD0-D88D5F1B5FBC"><title>Purpose</title> <p>This document explains how to implement

    16 an interface from Symbian platform to an IIC bus as a master channel. </p> <p><b>Intended

    17 Audience</b> </p> <p>Base porting engineers. </p> <p><b>Introduction</b> </p> <p>IIC

    18 buses (serial inter-chip buses) are a class of bus used to transmit non time-critical

    19 data between components of a hardware system. </p> </section>

    20 <section id="GUID-69ED3F3A-8D85-4940-B9C7-691081EC5E93"><title>Implementing a master channel</title> <p>To implement an IIC

    21 channel as master you must write a class extending <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>.

    22 You must implement certain pure virtual functions of the parent class in the

    23 subclass. Those functions and any other functions which you write in the subclass

    24 are called the Platform Specific Layer (PSL). The functions inherited from

    25 the parent class are called the Platform Independent Layer (PIL). </p> <p>The

    26 four functions you must implement are: </p> <ul>

    27 <li id="GUID-B49F1DAB-AB30-5C95-BFAF-93D8DC779371"><p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref>  </p> </li>

    28 <li id="GUID-A402D653-D8D5-5031-A647-ED02B95B4857"><p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref>  </p> </li>

    29 <li id="GUID-AF3B74BE-9193-51CD-B7E4-E721F2CCDC98"><p> <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref>  </p> </li>

    30 <li id="GUID-242CB2B6-0DB0-53A0-B951-1FACA037DEE0"><p> <xref href="GUID-A5E66E7E-E03B-3249-A5E5-F0E5DFC3B3EB.dita"><apiname>CheckHdr()</apiname></xref>  </p> </li>

    31 </ul> <p>You must also provide the following functionality: </p> <ul>

    32 <li id="GUID-7C3DDA6A-1976-518C-90D8-27BD1D2B9C23"><p>validation of input, </p> </li>

    33 <li id="GUID-6E61EE3F-D8A1-58B4-A129-61A42E710150"><p>interrupt service routines,

    34 and </p> </li>

    35 <li id="GUID-8018060E-C5D6-5C9C-BA63-05B9DAE47823"><p>reporting on transmission

    36 status using the callback function <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref> with

    37 the relevant error code. </p> </li>

    38 </ul> <p>Your implementation of the PSL will need to call functions of the

    39 PIL. You are restricted to using a certain subset of these. </p> <p><b>Implementing

    40 DoCreate()</b> </p> <p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref> is the second phase

    41 constructor of your class. Implement it to perform functionality including: </p> <ul>

    42 <li id="GUID-47401DEC-3072-541A-BE75-034E1ABFE40A"><p>call the PIL function <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>, </p> </li>

    43 <li id="GUID-C41E4C4B-10CE-5393-9326-83110FEBB244"><p>create the DFC queue

    44 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>

    45 <li id="GUID-D2E8E3FB-EF15-5257-BDD8-BA72D80EA129"><p>initialise the hardware,

    46 setting up interrupts, and </p> </li>

    47 <li id="GUID-851D395C-330B-5492-AD1A-A54A484ED63D"><p>initialise the other

    48 data structures representing the channel. </p> </li>

    49 </ul> <p><b>Implementing DoRequest()</b> </p> <p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> is

    50 the gateway function to the PSL. It configures the interface using the supplied

    51 configuration and processes transfers. It takes one argument <xref href="GUID-2803075B-3B59-3DF1-BB22-A6DF4DB6AA58.dita"><apiname>aTransaction</apiname></xref>,

    52 a pointer to a <xref href="GUID-1A326AA6-7C9F-3E61-9B55-34FCE771EB96.dita"><apiname>TIicBusTransaction</apiname></xref> object created by the

    53 client: you use the private data functions of the PIL (listed below) to extract

    54 the data needed to perform the associated transfers. Implement <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> with

    55 functionality including the following: </p> <ul>

    56 <li id="GUID-A7E758C2-89C0-5CCE-A5D2-1F7019CDF890"><p>Extract the transaction

    57 parameters, that is the transaction header and transfers (<xref href="GUID-73FDF24F-0B9D-3A97-B9BB-E021257E77F1.dita"><apiname>TIicBusTransfer</apiname></xref>), </p> </li>

    58 <li id="GUID-EF3B0B5A-E03B-58FF-8E8B-90EB6C7F5CFF"><p>configure the interface

    59 with the configuration supplied in the transaction header, </p> </li>

    60 <li id="GUID-A38796B7-A3F3-50D0-86DC-CCB4D3C69658"><p>set up the hardware

    61 to start the first transfer, that is </p> <ul>

    62 <li id="GUID-94CAE80B-2221-5664-85FB-B06666851DDB"><p>extract the first transfer

    63 for one direction by calling <xref href="GUID-2ADBFCF5-109F-33BA-97D1-44DA7D8604F2.dita"><apiname>GetTransHalfDuplexTransfer()</apiname></xref>, </p> </li>

    64 <li id="GUID-4613E372-DA10-5105-816F-1890A4314CDD"><p>and if the transfer

    65 is full duplex extract the first transfer for the second direction by calling <xref href="GUID-0C7ACFD8-279D-385D-8BF4-B870ABD185CE.dita"><apiname>GetTransFullDuplexTransferPtr()</apiname></xref>, </p> </li>

    66 </ul> <p>in each case filling hardware FIFO buffers, enabling interrupts and

    67 so on, </p> </li>

    68 <li id="GUID-B3CF4DEE-DAA2-5ADD-BA08-9861C457AF35"><p>call the PIL function <xref href="GUID-967E4167-498F-3714-8CFB-8273968C551B.dita"><apiname>StartSlaveTimeoutTimer()</apiname></xref>, </p> </li>

    69 <li id="GUID-48D2A463-EB97-5604-8106-9980AAE0FFE6"><p>instruct the hardware

    70 to start transmission, and </p> </li>

    71 <li id="GUID-45785C69-E8FB-5548-B8FF-3EA3EE45447F"><p>return either an error

    72 code or <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> </li>

    73 </ul> <p>The effect of calling <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> should be to

    74 start the sequence of transfers comprising the transaction. At the end of

    75 each transfer a hardware interrupt and associated DFC callback occurs. If

    76 the transfer was successful and a call to get the next transfers succeeds,

    77 the next transfer is set up. </p> <p><b>Implementing HandleSlaveTimeout()</b> </p> <p>Implement <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref>.

    78 This is the callback function which is triggered when a slave node times out.

    79 Implement it with functionality including: </p> <ul>

    80 <li id="GUID-37E4C87F-4980-5651-BD13-2AD8622A8F52"><p>stop the transmission, </p> </li>

    81 <li id="GUID-667655D7-76B0-5F0A-BFA5-F74B964AF982"><p>disable the hardware,

    82 and </p> </li>

    83 <li id="GUID-DCF7198C-BFB2-58EF-9014-C9BEB31F57E4"><p>call the PIL function <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref> with

    84 the <xref href="GUID-BAC2386E-8168-3CDB-9F9F-180319EF6920.dita"><apiname>KErrTimedOut</apiname></xref> error code. </p> </li>

    85 </ul> <p><b>Implementing CheckHdr()</b> </p> <p>Implement <xref href="GUID-B44147A7-D880-3510-A3F1-D73E9B5F8230.dita"><apiname>CheckHdr().</apiname></xref> This

    86 is the function which is called in the context of the client thread when the

    87 client calls <xref href="GUID-D0F8DF19-790F-3FE5-89E4-057C240AD3FE.dita"><apiname>QueueTransaction()</apiname></xref>. Implement it with the

    88 following functionality: </p> <ul>

    89 <li id="GUID-42548EF0-4A41-5095-8541-CDC8BF6032D4"><p>check if the header

    90 of the transaction is valid. </p> </li>

    91 </ul> <p><b>Using the Platform Independent Layer</b> </p> <p>You can only

    92 use certain functions of the PIL. Most are used to access private data of

    93 the parent class. Others provide functionality which is generic to IIC buses.

    94 These are: </p> <ul>

    95 <li id="GUID-1034BC57-BC77-5D7F-9385-3ACCC0EFF6DE"><p> <xref href="GUID-995FA70D-F28C-3AA6-BB6A-528210F3716E.dita"><apiname>DIicBusChannelMaster()</apiname></xref>,

    96 the constructor of the superclass <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref> with

    97 arguments representing the bus type and the duplex settings. </p> </li>

    98 <li id="GUID-27AE6A8A-3C0E-5DC3-917B-0F23D3D6E7C2"><p> <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>.

    99 Initialises <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. </p> </li>

   100 <li id="GUID-B90804B6-0A44-5764-B6AD-62F0A0E0C8C5"><p> <xref href="GUID-30953225-638A-3627-8183-544E127FE72C.dita"><apiname>StartSlaveTimeOutTimer()</apiname></xref>.

   101 Starts a timer which causes the <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref> callback

   102 to run if the transaction is not completed in the specified time. </p> </li>

   103 <li id="GUID-49D1C460-1DB5-537C-BF5C-5F9E5222C52F"><p> <xref href="GUID-2FC8CE8F-102C-3025-86B6-C903D26CD002.dita"><apiname>SetDfcQ()</apiname></xref>.

   104 Sets the driver's DFC queue to be used by DFCs in the PIL. </p> </li>

   105 <li id="GUID-B61C0B7E-43EF-55E6-9BA6-9791F3858D76"><p> <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref>.

   106 Called to signal the PIL about completed transactions, transmission errors

   107 and timeouts. </p> </li>

   108 <li id="GUID-4AC4BD6D-2123-5151-B744-8785A4D4E364"><p> <xref href="GUID-03DA2EEC-8E8C-30FC-9956-E721184FE43E.dita"><apiname>CancelTimeOut();</apiname></xref>.

   109 Cancels the timeout timer which monitors the transaction time. </p> </li>

   110 </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">

   111 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

   112 <thead>

   113 <row>

   114 <entry>Function</entry>

   115 <entry>Returns</entry>

   116 </row>

   117 </thead>

   118 <tbody>

   119 <row>

   120 <entry><p> <xref href="GUID-3D82EA8A-7F53-3204-A31C-B56707EF4C25.dita"><apiname>GetTransactionHeader</apiname></xref>  </p> </entry>

   121 <entry><p>A pointer to the configuration header. </p> </entry>

   122 </row>

   123 <row>

   124 <entry><p> <xref href="GUID-6E9E6C65-28C9-3B1F-9FBC-681FDACBB26A.dita"><apiname>GetTransHalfDuplexTfrPtr()</apiname></xref>  </p> </entry>

   125 <entry><p>A pointer to the head of the list of half duplex transfers. </p> </entry>

   126 </row>

   127 <row>

   128 <entry><p> <xref href="GUID-2672AD04-08F8-3756-AFFB-6EFCCAA335B8.dita"><apiname>GetTransFullDuplexTfrPtr()</apiname></xref>  </p> </entry>

   129 <entry><p>A pointer tothe head of the list of full duplex transfers. </p> </entry>

   130 </row>

   131 </tbody>

   132 </tgroup>

   133 </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">

   134 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

   135 <thead>

   136 <row>

   137 <entry>Function</entry>

   138 <entry>Returns</entry>

   139 </row>

   140 </thead>

   141 <tbody>

   142 <row>

   143 <entry><p> <xref href="GUID-2D2CB373-D370-3D6E-B57D-A87EB993A76C.dita"><apiname>GetTferType</apiname></xref>  </p> </entry>

   144 <entry><p>The transfer type, EMasterRead or <xref href="GUID-5E76AC81-4074-337D-86E4-B3FC14062B51.dita"><apiname>EMasterWrite</apiname></xref>,

   145 defined in the enumeration <xref href="GUID-5FBF20DE-E998-3281-A85E-EF56A1FDDFA3.dita"><apiname>TReqType</apiname></xref>. </p> </entry>

   146 </row>

   147 <row>

   148 <entry><p> <xref href="GUID-3B3A6E26-8415-3810-9C35-B92EFA0A91C0.dita"><apiname>GetTferBufGranularity</apiname></xref>  </p> </entry>

   149 <entry><p>The size of the buffer item in bits, typically 8 or 16. </p> </entry>

   150 </row>

   151 <row>

   152 <entry><p> <xref href="GUID-F80C258F-EACC-3742-BFE1-F226F8B94917.dita"><apiname>GetTferBuffer</apiname></xref>  </p> </entry>

   153 <entry><p>A pointer to the buffer where the data is stored. </p> </entry>

   154 </row>

   155 <row>

   156 <entry><p> <xref href="GUID-B1C1BF16-203A-3904-BDFD-5452CEC815DF.dita"><apiname>GetTferNextTfer</apiname></xref>  </p> </entry>

   157 <entry><p>A pointer to the next transfer in the transaction. </p> </entry>

   158 </row>

   159 </tbody>

   160 </tgroup>

   161 </table> </section>

   162 </conbody><related-links>

   163 <link href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita"><linktext>IIC Kernel-side

   164 Implementation Guide:  Generic Considerations</linktext></link>

   165 <link href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita"><linktext>IIC Kernel-side

   166 Implementation Guide:   Slave Channel</linktext></link>

   167 <link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client of

   168 Master  Channel Implementation Tutorial</linktext></link>

   169 <link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client of

   170 Slave                 Channel Implementation Tutorial</linktext></link>

   171 <link href="GUID-B2F86F54-EF50-56DB-ADF7-15325AC9324D.dita"><linktext>IIC Guide</linktext>

   172 </link>

   173 <link href="GUID-99FC067C-0AED-5373-AF63-8DB7FF5C1F7E.dita"><linktext>SPI Technology

   174 Guide</linktext></link>

   175 <link href="GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita"><linktext>I2C Technology

   176 Guide</linktext></link>

   177 </related-links></concept>