<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84" xml:lang="en"><title>IIC Kernel-side
Implementation Guide: Master Channel</title><shortdesc>This document explains how to implement an interface from Symbian
platform to an IIC bus as a master channel. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-38D02829-2B52-4E2E-ABD0-D88D5F1B5FBC"><title>Purpose</title> <p>This document explains how to implement
an interface from Symbian platform to an IIC bus as a master channel. </p> <p><b>Intended
Audience</b> </p> <p>Base porting engineers. </p> <p><b>Introduction</b> </p> <p>IIC
buses (serial inter-chip buses) are a class of bus used to transmit non time-critical
data between components of a hardware system. </p> </section>
<section id="GUID-69ED3F3A-8D85-4940-B9C7-691081EC5E93"><title>Implementing a master channel</title> <p>To implement 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 functions of the parent class in the
subclass. Those functions and any other functions which you write in the subclass
are called the Platform Specific Layer (PSL). The functions inherited from
the parent class are called the Platform Independent Layer (PIL). </p> <p>The
four functions you must implement are: </p> <ul>
<li id="GUID-B49F1DAB-AB30-5C95-BFAF-93D8DC779371"><p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref>  </p> </li>
<li id="GUID-A402D653-D8D5-5031-A647-ED02B95B4857"><p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref>  </p> </li>
<li id="GUID-AF3B74BE-9193-51CD-B7E4-E721F2CCDC98"><p> <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref>  </p> </li>
<li id="GUID-242CB2B6-0DB0-53A0-B951-1FACA037DEE0"><p> <xref href="GUID-A5E66E7E-E03B-3249-A5E5-F0E5DFC3B3EB.dita"><apiname>CheckHdr()</apiname></xref>  </p> </li>
</ul> <p>You must also provide the following functionality: </p> <ul>
<li id="GUID-7C3DDA6A-1976-518C-90D8-27BD1D2B9C23"><p>validation of input, </p> </li>
<li id="GUID-6E61EE3F-D8A1-58B4-A129-61A42E710150"><p>interrupt service routines,
and </p> </li>
<li id="GUID-8018060E-C5D6-5C9C-BA63-05B9DAE47823"><p>reporting on 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>
</ul> <p>Your implementation of the PSL will need to call functions of the
PIL. You are restricted to using a certain 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. Implement it to perform functionality including: </p> <ul>
<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>
<li id="GUID-C41E4C4B-10CE-5393-9326-83110FEBB244"><p>create the DFC 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>
<li id="GUID-D2E8E3FB-EF15-5257-BDD8-BA72D80EA129"><p>initialise the hardware,
setting up interrupts, and </p> </li>
<li id="GUID-851D395C-330B-5492-AD1A-A54A484ED63D"><p>initialise the other
data structures representing the channel. </p> </li>
</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 PSL. It configures the interface using the supplied
configuration and processes transfers. It takes one argument <xref href="GUID-2803075B-3B59-3DF1-BB22-A6DF4DB6AA58.dita"><apiname>aTransaction</apiname></xref>,
a pointer to a <xref href="GUID-1A326AA6-7C9F-3E61-9B55-34FCE771EB96.dita"><apiname>TIicBusTransaction</apiname></xref> object created by the
client: you use the private data functions of the PIL (listed below) to 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>
<li id="GUID-A7E758C2-89C0-5CCE-A5D2-1F7019CDF890"><p>Extract the transaction
parameters, that is the transaction header and transfers (<xref href="GUID-73FDF24F-0B9D-3A97-B9BB-E021257E77F1.dita"><apiname>TIicBusTransfer</apiname></xref>), </p> </li>
<li id="GUID-EF3B0B5A-E03B-58FF-8E8B-90EB6C7F5CFF"><p>configure the interface
with the configuration supplied in the transaction header, </p> </li>
<li id="GUID-A38796B7-A3F3-50D0-86DC-CCB4D3C69658"><p>set up the hardware
to start the first transfer, that is </p> <ul>
<li id="GUID-94CAE80B-2221-5664-85FB-B06666851DDB"><p>extract the first transfer
for one direction by calling <xref href="GUID-2ADBFCF5-109F-33BA-97D1-44DA7D8604F2.dita"><apiname>GetTransHalfDuplexTransfer()</apiname></xref>, </p> </li>
<li id="GUID-4613E372-DA10-5105-816F-1890A4314CDD"><p>and if the transfer
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>
</ul> <p>in each case filling hardware FIFO buffers, enabling interrupts and
so on, </p> </li>
<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>
<li id="GUID-48D2A463-EB97-5604-8106-9980AAE0FFE6"><p>instruct the hardware
to start transmission, and </p> </li>
<li id="GUID-45785C69-E8FB-5548-B8FF-3EA3EE45447F"><p>return either an error
code or <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> </li>
</ul> <p>The effect of calling <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> should be to
start the sequence of transfers comprising the transaction. At the end of
each transfer a hardware interrupt and associated DFC callback occurs. If
the transfer was successful and a call to get the next transfers succeeds,
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>.
This is the callback function which is triggered when a slave node times out.
Implement it with functionality including: </p> <ul>
<li id="GUID-37E4C87F-4980-5651-BD13-2AD8622A8F52"><p>stop the transmission, </p> </li>
<li id="GUID-667655D7-76B0-5F0A-BFA5-F74B964AF982"><p>disable the hardware,
and </p> </li>
<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
the <xref href="GUID-BAC2386E-8168-3CDB-9F9F-180319EF6920.dita"><apiname>KErrTimedOut</apiname></xref> error code. </p> </li>
</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 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>
<li id="GUID-42548EF0-4A41-5095-8541-CDC8BF6032D4"><p>check if the header
of the transaction is valid. </p> </li>
</ul> <p><b>Using the Platform Independent Layer</b> </p> <p>You can only
use certain functions of the PIL. Most are used to access private data of
the parent class. Others provide functionality which is generic to IIC buses.
These are: </p> <ul>
<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>
<li id="GUID-27AE6A8A-3C0E-5DC3-917B-0F23D3D6E7C2"><p> <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>.
Initialises <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. </p> </li>
<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 is not completed in the specified time. </p> </li>
<li id="GUID-49D1C460-1DB5-537C-BF5C-5F9E5222C52F"><p> <xref href="GUID-2FC8CE8F-102C-3025-86B6-C903D26CD002.dita"><apiname>SetDfcQ()</apiname></xref>.
Sets the driver's DFC queue to be used by DFCs in the PIL. </p> </li>
<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 errors
and timeouts. </p> </li>
<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>
</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">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Function</entry>
<entry>Returns</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-3D82EA8A-7F53-3204-A31C-B56707EF4C25.dita"><apiname>GetTransactionHeader</apiname></xref>  </p> </entry>
<entry><p>A pointer to the configuration header. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-6E9E6C65-28C9-3B1F-9FBC-681FDACBB26A.dita"><apiname>GetTransHalfDuplexTfrPtr()</apiname></xref>  </p> </entry>
<entry><p>A pointer to the head of the list of half duplex transfers. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-2672AD04-08F8-3756-AFFB-6EFCCAA335B8.dita"><apiname>GetTransFullDuplexTfrPtr()</apiname></xref>  </p> </entry>
<entry><p>A pointer tothe head of the list of full duplex transfers. </p> </entry>
</row>
</tbody>
</tgroup>
</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">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Function</entry>
<entry>Returns</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-2D2CB373-D370-3D6E-B57D-A87EB993A76C.dita"><apiname>GetTferType</apiname></xref>  </p> </entry>
<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>
</row>
<row>
<entry><p> <xref href="GUID-3B3A6E26-8415-3810-9C35-B92EFA0A91C0.dita"><apiname>GetTferBufGranularity</apiname></xref>  </p> </entry>
<entry><p>The size of the buffer item in bits, typically 8 or 16. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-F80C258F-EACC-3742-BFE1-F226F8B94917.dita"><apiname>GetTferBuffer</apiname></xref>  </p> </entry>
<entry><p>A pointer to the buffer where the data is stored. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-B1C1BF16-203A-3904-BDFD-5452CEC815DF.dita"><apiname>GetTferNextTfer</apiname></xref>  </p> </entry>
<entry><p>A pointer to the next transfer in the transaction. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
</conbody><related-links>
<link href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita"><linktext>IIC Kernel-side
Implementation Guide:  Generic Considerations</linktext></link>
<link href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita"><linktext>IIC Kernel-side
Implementation Guide:   Slave Channel</linktext></link>
<link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client of
Master  Channel Implementation Tutorial</linktext></link>
<link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client of
Slave                 Channel Implementation Tutorial</linktext></link>
<link href="GUID-B2F86F54-EF50-56DB-ADF7-15325AC9324D.dita"><linktext>IIC Guide</linktext>
</link>
<link href="GUID-99FC067C-0AED-5373-AF63-8DB7FF5C1F7E.dita"><linktext>SPI Technology
Guide</linktext></link>
<link href="GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita"><linktext>I2C Technology
Guide</linktext></link>
</related-links></concept>