<?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-C9644081-004E-5DA0-8133-A32EEA91EF5E" xml:lang="en"><title>IIC SHAI Implementation Layer: Slave Channel</title><shortdesc>This document explains how to implement a slave channel

in the SHAI implementation layer of IIC. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-48EF587B-8C61-47FA-B311-18594D3B54CD"><title>Purpose</title> <p>This document explains how to implement a slave channel in 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-5AF2B3DD-0A5B-4E3E-AF8A-D1522E540D7A"><title>Implementing

a slave channel</title> <p>To implement the SHAI implementation layer

of an IIC channel as slave you must write a class extending <xref href="GUID-22FF70C1-A805-3EBB-B142-15FD16D00837.dita"><apiname>DIicBusChannelSlave</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-107E2432-19BB-55D8-9100-A0F27D0C7ED2"><p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref>  </p> </li>

<li id="GUID-567D0C13-D99B-5901-8833-F0E7FE4EA24E"><p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref>  </p> </li>

<li id="GUID-4B0653EC-AF4F-53C9-92F4-C9950D58C742"><p> <xref href="GUID-2958D2DF-696B-3493-985D-E6DE4BBCD74C.dita"><apiname>ProcessData()</apiname></xref>  </p> </li>

<li id="GUID-028033AA-63D9-5AB0-9645-7F9397EEEEA7"><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-546A43C9-03BC-54D9-B77A-B88D9D74F817"><p>From the constructor,

call the constructor of the base class <xref href="GUID-22FF70C1-A805-3EBB-B142-15FD16D00837.dita"><apiname>DIicBusChannelSlave</apiname></xref> with arguments for bus type and duplex settings, </p> </li>

<li id="GUID-B26256C0-3CC0-59DA-9A5E-99B6EEACBDA6"><p>assign the channel

number (if you are using the IIC Controller) and channel ID, and </p> </li>

<li id="GUID-D9031D14-27DF-5A2D-B0FB-E79D28E4DECE"><p>report events

signalled by the hardware by calling the <xref href="GUID-5111CCD6-E449-30B7-844F-8273FBCA97DE.dita"><apiname>NotifyClient()</apiname></xref> callback function with the appropriate trigger. </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 the Platform Specific Layer</b> </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 with

functionality including: </p> <ul>

<li id="GUID-A06C90F8-F423-5FD0-BE3A-DC5072503F16"><p>If you are using

the IIC controller, set the channel number, </p> </li>

<li id="GUID-5740E282-41F2-5128-A2AB-5429D959F270"><p>call the <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref> method of the base class, and </p> </li>

<li id="GUID-202230E9-C634-5384-8ADF-3C8DD8AF9FFD"><p>set the <xref href="GUID-D389A526-3974-3EB5-95F5-50EAFE7B48E0.dita"><apiname>iChannelId</apiname></xref> member to an ID to be returned to the SHAI implementation

layer, which will use it to create a channel ID which is unique with

respect to other opened slave channels. </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. Implement

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

<li id="GUID-1671D196-1C71-58EF-892F-6F723133300B"><p>configure the

interface, </p> </li>

<li id="GUID-7085B7DE-B6DD-5964-952A-4F956C9836D5"><p>set triggers

and initiate transfers, and </p> </li>

<li id="GUID-8C59A6CE-4980-5F6F-90AD-551064EE8A92"><p>disable interrupts

in the event of an abort. </p> </li>

</ul> <p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname> DoRequest()</apiname></xref> shall be called with an

argument representing one of various possible operations. </p> <ul>

<li id="GUID-2D0A07D3-95E1-5AF0-B960-A9558DA2935C"><p>The argument

is <xref href="GUID-C504873A-5B30-39C6-90A8-618B42C409D5.dita"><apiname>EAsyncConfigPwrUp</apiname></xref> when the client called the

client API with instructions to complete asynchronously. The SHAI

implementation layer should power up and configure the hardware and

then call <xref href="GUID-23D0DB11-0820-3C5A-B4E9-D10398E8FAC3.dita"><apiname>ChanCaptureCallback()</apiname></xref> with the result

as argument. </p> </li>

<li id="GUID-94087E4A-F192-56B6-A03C-22895E90F039"><p>The argument

is <xref href="GUID-A79F9A93-984F-3024-92F0-544D0A2D8BBA.dita"><apiname>ESyncConfigPwrUp</apiname></xref> when the client called client

called the client API with instructions to complete synchronously.

The SHAI implementation layer should power up and configure the hardware

and return the result. </p> </li>

<li id="GUID-8747FA9D-E03C-545C-941E-38657E943339"><p>The argument

is <xref href="GUID-59D9D3BE-400C-3B61-9208-535D55D59BF3.dita"><apiname>EPowerDown</apiname></xref> when the client called client called

the client API. The SHAI implementation layer should disable the interrupts,

stop any ongoing or outstanding operations and stop or reset the hardware

to its initial state. </p> </li>

<li id="GUID-D5E42E03-5016-57E7-B816-3777B0207660"><p>The argument

is <xref href="GUID-5CE38A1F-7AA1-3377-BFBB-4871730B1590.dita"><apiname>ETransmit</apiname></xref> when the client called <xref href="GUID-74BA3796-65DE-39A1-A50F-78394AA0632E.dita#GUID-74BA3796-65DE-39A1-A50F-78394AA0632E/GUID-CB8904EA-474D-3AFB-8519-248F104A10AB"><apiname>Iic::SetNotificationTrigger()</apiname></xref> with any of the transmit triggers as argument. The SHAI implementation

layer should initialize the hardware and set up transmission buffers.

In a typical implementation, if the transmission has not yet started

it should also fill up the transmit FIFO and enable interrupts to

prepare for transmission, but this is not necessary if the transmission

is ongoing and the argument <xref href="GUID-5CE38A1F-7AA1-3377-BFBB-4871730B1590.dita"><apiname>ETransmit</apiname></xref> was passed

because of a transmit underrun. </p> </li>

<li id="GUID-2F7EA8A0-423A-5296-AF96-2A63377F55DE"><p>The argument

is <xref href="GUID-5BA7AA55-E78D-3807-A6E3-4596A106B94B.dita"><apiname>EReceive</apiname></xref> if the client called <xref href="GUID-74BA3796-65DE-39A1-A50F-78394AA0632E.dita#GUID-74BA3796-65DE-39A1-A50F-78394AA0632E/GUID-B88F5929-78F3-3CFD-B288-93B2EE883463"><apiname>Iic::SetNotificationTrigger</apiname></xref> with any of the receive triggers as argument. The SHAI implementation

layer should initialize the hardware and set up receive buffers. In

a typical implementation, if the transmission has not yet started

it should also flush or fill the receive FIFO and enable interrupts,

but this is not necessary if the transmission is ongoing and the argument <xref href="GUID-5BA7AA55-E78D-3807-A6E3-4596A106B94B.dita"><apiname>EReceive</apiname></xref> was passed because of a receive overrun. </p> </li>

<li id="GUID-9692F677-FD7E-589F-BF8B-9CAB97764202"><p>The argument

is <xref href="GUID-966F7C7B-F8B1-334E-998B-BAC4C6BF86DA.dita"><apiname>EAbort</apiname></xref> if the timer of the master activity has

expired. The SHAI implementation layer should stop the transfer by

disabling interrupts, stopping ongoing and outstanding operations

and resetting the hardware and return failure. </p> </li>

</ul> <p><b>Implementing ProcessData()</b> </p> <p>The easiest way

to understand this, is to review the template port at <filepath>\os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic\iic_slave</filepath>.</p><p><xref href="GUID-2958D2DF-696B-3493-985D-E6DE4BBCD74C.dita"><apiname>ProcessData()</apiname></xref> is the function called by

the platform independent layer in response to <xref href="GUID-5111CCD6-E449-30B7-844F-8273FBCA97DE.dita"><apiname>NotifyClient()</apiname></xref>. It has two arguments representing a trigger <codeph>aTrigger</codeph> and a callback <codeph>aCb</codeph>. You implement it to modify

the callback </p> <ul>

<li id="GUID-0BB2E7AA-4648-5006-81BF-78B83462C73F"><p> <xref href="GUID-334979E2-7CC0-3736-BFE2-8F92305CC47B.dita"><apiname>aTrigger</apiname></xref>, a trigger of class <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref>, and </p> </li>

<li id="GUID-3EE01C52-1D50-5514-A95B-7ED30558BC8C"><p> <xref href="GUID-68BD6AE8-7FF5-310D-A8A0-D28FA3994B3A.dita"><apiname>aCb</apiname></xref>, a callback of class <xref href="GUID-7D3ABED1-42FE-3A89-8898-C3854D201BC9.dita"><apiname>TIicBusSlaveCallback</apiname></xref>. </p> </li>

</ul> <p>You implement the function to update the callback according

to the value of the trigger. </p> <ul>

<li id="GUID-ADFFED1D-C9D1-5EFA-B846-4B6537E2F408"><p>If the trigger

is a receive trigger, update the callback with the number of words

already received to the buffer by calling </p> <codeblock id="GUID-2C227263-5A41-5FCD-9206-C8DEB775CB4F" xml:space="preserve">aCb-&gt;SetRxWords(numWordsReceived);</codeblock> </li>

<li id="GUID-2A567339-C9BB-56D1-8E3B-71DA3CDAEC4C"><p>If the trigger

is a transmit trigger, update the callback with the number of words

already transmitted (moved to the hardware transmit FIFO) by calling </p> <codeblock id="GUID-D92F489C-9214-5D4A-BF29-AAEBCE3353AE" xml:space="preserve">aCb-&gt;SetTxWords(numWordsTransmitted);</codeblock> </li>

<li id="GUID-B447C1B5-FEA0-5764-8507-55041088194E"><p>Whether the

trigger is receive or transmit, update the trigger member of the callback

containing the accumulated event history by calling </p> <codeblock id="GUID-377BA25F-3FE5-5A3A-B671-7F5CA007FB2D" xml:space="preserve">aCb-&gt;SetTrigger(trigger | aCb-&gt;GetTrigger());</codeblock> <p>where <codeph>trigger</codeph> is one of the receive or transmit

triggers or <xref href="GUID-1D10124D-F27E-33C3-B803-FEBDEB2B7964.dita"><apiname>EGeneralBusError</apiname></xref>. </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 if the

client tries to capture the channel. Implement it with the following

functionality: </p> <ul>

<li id="GUID-53140F3D-A4B6-5AA8-955E-55DE3C69E063"><p>check if the

specified configuration  is valid. </p> </li>

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

only use certain functions of the PIL. They provide functionality

which is generic to IIC buses. They are: </p> <ul>

<li id="GUID-3195CC6D-84CF-5FD8-93F7-CC8E4F88FCFB"><p> <xref href="GUID-0A25EDF8-8DC6-33A0-8CD3-880898D2E61E.dita"><apiname>DIicBusChannelSlave()</apiname></xref>. The constructor of the superclass DIicBusChannelSlave. </p> </li>

<li id="GUID-47BA511F-1430-5B13-ABEC-972238B8C4C7"><p> <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>. Initializes <xref href="GUID-22FF70C1-A805-3EBB-B142-15FD16D00837.dita"><apiname>DIicBusChannelSlave</apiname></xref>. </p> </li>

<li id="GUID-695E3D51-2E28-5AC6-B960-D911A8BB679C"><p> <xref href="GUID-23D0DB11-0820-3C5A-B4E9-D10398E8FAC3.dita"><apiname>ChanCaptureCallback()</apiname></xref>. Called with the error code when asynchronous channel capture has

completed in response to <xref href="GUID-6612D537-67B8-30E1-AB97-4B75A866DB6F.dita"><apiname>DoRequest(EAsyncConfigPwrUp)</apiname></xref>. </p> </li>

<li id="GUID-9979C465-5988-5710-BD4D-428417234185"><p> <xref href="GUID-5111CCD6-E449-30B7-844F-8273FBCA97DE.dita"><apiname>NotifyClient()</apiname></xref>. Called to notify the PIL (which then notifies the client) that

a hardware event of the passed in type has occurred. </p> </li>

<li id="GUID-9547DCEE-13C9-5045-8910-2A8BD0FECC58"><p> <xref href="GUID-1BC13C5C-A0A5-3D7C-953E-8499B14B2E93.dita"><apiname>SetMasterWaitTime()</apiname></xref>. Sets the timeout for the master to respond after the transmission

has been started. </p> </li>

<li id="GUID-CBF88624-1DFE-5B20-9220-0DE9176620F5"><p> <xref href="GUID-B8BAB30F-A1C7-3F33-B5B0-C2ADFB83D941.dita"><apiname>GetMasterWaitTime()</apiname></xref>. Gets the timeout for the master to respond after the transmission

has been started. </p> </li>

<li id="GUID-468FEE59-6570-5C9F-9774-09C540B6B8A3"><p> <xref href="GUID-04E9F6A6-B3A0-3216-B09E-25AAF79DC7DD.dita"><apiname>SetClientWaitTime()</apiname></xref>. Sets the client wait time within which it is expected to respond

with the next operation. </p> </li>

<li id="GUID-4EE6EAC2-66A8-5BFC-BD25-D376CA790120"><p> <xref href="GUID-C3046454-F0ED-3D7B-93BC-02211B2470C8.dita"><apiname>GetClientWaitTime()</apiname></xref>. Gets the client wait time within which it is expected to respond

with the next operation. </p> </li>

</ul> <p><b>Implementing event notification</b> </p> <p>A slave channel

reports events on the hardware by calling the PIL function <xref href="GUID-5111CCD6-E449-30B7-844F-8273FBCA97DE.dita"><apiname>NotifyClient()</apiname></xref> to pass the following notifications under

the stated conditions. </p> <ul>

<li id="GUID-F3CDDE98-9DEF-55A9-B1A5-8E84C26A3EE3"><p>Pass <xref href="GUID-6E213643-B02E-35F0-AF1F-BF79134DA8E1.dita"><apiname>ERxAllBytes</apiname></xref> if the transmission has stopped with all bytes

received. </p> </li>

<li id="GUID-9FFE9AE8-DF13-5A1E-BBCB-315AA8DA377D"><p>Pass <xref href="GUID-1FFA3657-452F-3BB2-88C7-663395757613.dita"><apiname>ETxAllBytes</apiname></xref> if the transmission has stopped with all bytes

transmitted. </p> </li>

<li id="GUID-66E08813-61B8-5300-BDD9-CBC3C779C290"><p>Pass <xref href="GUID-8CC48D05-A472-3A95-AEDC-1208F1522B5F.dita"><apiname>ERxUnderrun</apiname></xref> if the transmission has been stopped but the

receive buffer provided by the client is not full, indicating that

the master has sent less data than expected. </p> </li>

<li id="GUID-1E7D1FD4-D97B-59B3-8C2B-AF17073F7166"><p>Pass <xref href="GUID-90F30E77-211E-333E-AF0B-DA2A62761A11.dita"><apiname>ERxOverrun</apiname></xref> if the transmission has not been stopped but

the receive buffer provided by the client is full. The client should

respond to a receive overrun by </p> <ul>

<li id="GUID-B426810A-8137-5221-8965-4EDA901331D0"><p>providing new

receive buffer, and </p> </li>

<li id="GUID-7F452F0B-FC12-5FF2-AD9B-5A267F96692F"><p>resetting its

receive notification triggers for instance by calling <codeph>SetNotificationTrigger(ERxAllBytes)</codeph>. </p> </li>

</ul> <p>To make this possible the SHAI implementation layer should

try to keep the receive hardware FIFO at the lowest possible level. </p> </li>

<li id="GUID-1ED0E6C5-94D0-5AA1-9D3D-318391C167F4"><p>Pass <xref href="GUID-F51FDBA8-E904-3091-BFF1-43B968389C68.dita"><apiname>ETxUnderrun</apiname></xref> if the transmission has not been stopped but

all the data in the transmit buffer provided by the client has been

transferred. The client should respond to a transmit underrun by </p> <ul>

<li id="GUID-C898DAD3-B7A6-5E35-B0D2-F7919FD402A1"><p>providing new

transmit buffer, and </p> </li>

<li id="GUID-0CC17326-1FFF-5B45-A4D9-6182B2A46C8E"><p>resetting its

transmit notification triggers for instance by calling <codeph>SetNotificationTrigger(ETxAllBytes)</codeph>. </p> </li>

</ul> <p>To make this possible the SHAI implementation layer should

try to keep the transmit hardware FIFO at the highest possible level. </p> </li>

<li id="GUID-3D823BF3-5AB5-565C-83B3-F7E7C4550EEA"><p>Pass <xref href="GUID-C29FA887-BBDA-35D2-9ED2-58083F85AD87.dita"><apiname>ETxOverrun</apiname></xref> if the transmission has been stopped but not

all the data in the transmit buffer provided by the client has been

transferred. This indicates that the client specified a bigger buffer

for the transmission than the master needed to read from the slave. </p> </li>

<li id="GUID-1CA68D76-14AF-5FF9-883A-60B6BC2A72F2"><p>Pass <xref href="GUID-1D10124D-F27E-33C3-B803-FEBDEB2B7964.dita"><apiname>EGeneralBusError</apiname></xref> if a bus error has occurred, that is if

an interrupt signals a bus overrun or underrun indicating data corruption. </p> </li>

</ul> </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-0C8318B1-71D7-5384-97EB-85CBBC3E6B84.dita"><linktext>IIC

SHAI Implementation Layer: Master 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>