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