<?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 SHAI Implementation Layer: Master Channel</title><shortdesc>This document explains how to implement the a master channel
in the SHAI implementation layer of IIC. </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 a master channel on the
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
buses that IIC can operate on) 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>You should read and understand the template
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
the master channel.</p><p>To implement the SHAI implementation layer
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
functions of the parent class in the subclass. Those functions and
any other functions which you write in the subclass are called the
SHAI implementation layer. 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 SHAI implementation layer 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>initialize the
hardware, setting up interrupts, and </p> </li>
<li id="GUID-851D395C-330B-5492-AD1A-A54A484ED63D"><p>initialize 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 SHAI implementation layer. It configures
the interface using the supplied configuration and processes transactions.
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 protected 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 <codeph>DoRequest()</codeph> should
be to start the sequence of transfers comprising the transaction.
Typically, at the end of each transfer a hardware interrupt and associated
DFC callback occurs. If the PIL function <codeph>StartSlaveTimeout()</codeph> was called to monitor the duration of an individual transfer, the
PIL function <codeph>CancelTimeout()</codeph> should be called to
cancel the timer. If the transfer was successful and a call to get
the next transfers succeeds, the next transfer is set up. This continues
until either all the transfers have been processed, or there is an
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
time, and in such case some SHAI implementation layer-specific recovery
will be required; this is to be provided by the implementation of
 <codeph>HandleSlaveTimeout()</codeph>. 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 <codeph>CompleteRequest()</codeph> 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>. Initializes <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. </p> </li>
<li><p>•<codeph>SetDfcQ()</codeph>. Sets the driver's DFC queue to
be used by DFCs in the PIL. </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 (or transfer, SHAI implementation
layer decides) is not completed in the specified time. </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>
<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>
</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> <codeph>GetTransactionHeader() </codeph> </p> </entry>
<entry><p>A pointer to the configuration header. </p> </entry>
</row>
<row>
<entry><p> <codeph>GetTransHalfDuplexTfrPtr()</codeph>  </p> </entry>
<entry><p>A pointer to the head of the list of half duplex transfers. </p> </entry>
</row>
<row>
<entry><p> <codeph>GetTransFullDuplexTfrPtr()</codeph>  </p> </entry>
<entry><p>A pointer to the head of the list of full duplex transfers. </p> </entry>
</row>
<row>
<entry><p><codeph>GetTransCallback()</codeph></p></entry>
<entry><p>A pointer to the callback function</p></entry>
</row>
<row>
<entry><p><codeph>GetTransFlags()</codeph></p></entry>
<entry><p>a pointer to the transaction flags</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-779C14B5-7D9D-3582-BE22-21CB668FADE6.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-D55D721A-4F5C-3B94-9351-971269E94493.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-8A2E8454-957C-3F24-AF23-CF375C30EB05.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-FD0F5059-1B2B-3477-907C-9BC50D6CF6AE.dita"><apiname>GetTferNextTfer()</apiname></xref>  </p> </entry>
<entry><p>A pointer to the next transfer in the transaction. </p> </entry>
</row>
</tbody>
</tgroup>
</table><note>In addition to the above functions, there are additional
functions for accessing transactions with preambles, extending transactions
(multitransactions) and extended transactions with preamble. Refer
to the header file for details on these functions.</note> </section>
</conbody><related-links>
<link href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita"><linktext>IIC
SHAI Implementation Layer:  Generic Considerations</linktext></link>
<link href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita"><linktext>IIC
SHAI implementation Layer: Slave Channel</linktext></link>
<link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client
of Master Channel Tutorial</linktext></link>
<link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client
of Slave Channel Tutorial</linktext></link>
<link href="GUID-B2F86F54-EF50-56DB-ADF7-15325AC9324D.dita"><linktext>IIC
Concepts</linktext></link>
<link href="GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita"><linktext>I2C
Technology Guide</linktext></link>
</related-links></concept>