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