<?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-C24A5B52-0B40-53B2-BF85-6ECC35BDCBA5" xml:lang="en"><title>IIC Implementation Guide</title><shortdesc>Describes how to implement the IIC platform service.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This document describes the overview of how to implement the IIC
platform service APIs and directs you to more specific documentation. </p>
<section id="GUID-16DD5496-C5F7-43C3-9C90-119E32AD50FE"><title>Purpose</title> <p>The IIC platform service APIs provides a means of accessing devices
that are connected onto a multi-wire bus within the phone. These platform
service APIs rely on hardware-specific implementation in the SHAI
implementation layer of the IIC implementation. This hardware-specific
implementation is primarily creating concrete hardware-specific implementations
of functions defined in the Platform Independent Layer (PIL),.</p> <p><b>Intended Audience:</b> </p> <p>This document is intended for
hardware device implementers who want to write adaptation software
to use their specific serial bus hardware with IIC. </p> </section>
<section id="GUID-A0142A52-534D-4C0D-8145-85C0A84DDBB5"><title>Background</title><p>There are two main forms of IIC operation: </p><ul>
<li><p>Master operation</p></li>
<li><p>Slave mode </p></li>
</ul><p>A master node on a bus controls transactions and is responsible
for sending commands along the bus to select the slave node which
is to send or receive the commands and data. A slave node receives
instructions from a master node and sends or receives commands and
data. The OS device drivers may act as a slave or a master node, or
in some bus technologies, the role of master and slave can be exchanged.</p><p>IIC has channels, which represent a connection between two nodes
on the bus. The channel has a queue for commands and will process
each command in turn. </p><p>A device driver can either use the IIC
Controller to access channels, or if there is a dedicated node that
is going to be used by a particular device driver, then the device
driver can talk directly to that node through IIC without using the
IIC Controller.</p> </section>
<section id="GUID-5CF49F33-E7B8-4FE6-AB97-A6B5EB38F9FF"><title>The
IIC platform service API</title> <p>The <codeph>IicBus</codeph> class
provides the platform service API for device drivers that want to
use the IIC Controller. For Controller-less operation, the platform
service API is formed by the <codeph>DIicBusChannelMaster</codeph>, <codeph>DIicBusChannelSlave</codeph> and <codeph>DIicBusChannelMasterSlave</codeph> classes.</p> <p>A summary of methods in the <codeph>IicBus</codeph> class are : </p> <table id="GUID-C77D090D-F2CA-500A-9E75-EDF80CB60CA5">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>Method</b>  </p> </entry>
<entry><p> <b>Purpose</b>  </p> </entry>
</row>
<row>
<entry><p>QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction) </p> </entry>
<entry><p>Queues a transaction for synchronous completion. </p> </entry>
</row>
<row>
<entry><p>QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction,
TIicBusCallback* aCallback) </p> </entry>
<entry><p>Queues a transaction for asynchronous completion. </p> </entry>
</row>
<row>
<entry><p>CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction) </p> </entry>
<entry><p>Cancels a previously queued transaction (if the transaction
was queued asynchronously). </p> </entry>
</row>
<row>
<entry><p>CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback*
aCallback, TInt&amp; aChannelId, TBool aAsynch=EFalse) </p> </entry>
<entry><p>Capture a slave channel. </p> <p>The aAsynch parameter indicates
if this is to be done synchronously or asynchronously. The default
is synchronous. </p> </entry>
</row>
<row>
<entry><p>ReleaseChannel(TInt aChannelId) </p> </entry>
<entry><p>Release a previously captured Slave channel. </p> </entry>
</row>
<row>
<entry><p>RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8
aBufGranularity, TInt8 aNumWords, TInt8 aOffset) </p> </entry>
<entry><p>Register a receive buffer with this slave channel. </p> </entry>
</row>
<row>
<entry><p>RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8
aBufGranularity, TInt8 aNumWords, TInt8 aOffset) </p> </entry>
<entry><p>Register a transmit buffer with this slave channel. </p> </entry>
</row>
<row>
<entry><p>SetNotificationTrigger(TInt aChannelId, TInt aTrigger) </p> </entry>
<entry><p>For a transmit operation, this sets the notification trigger,
sets the receive path and starts a transmit operation (if the node
is being addressed). For a receive operation, this sets the notification
trigger. </p> </entry>
</row>
<row>
<entry><p>StaticExtension(TUint aId, TUint aFunction, TAny* aParam1,
TAny* aParam2) </p> </entry>
<entry><p>Interface to provide extended functionality. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>The platform service APIs for controller-less operation
are almost exactly the same, but with the addition of channel constructors
and destructors.<note> Please refer to <filepath>iic.h</filepath>, <filepath>iic_channel.cpp</filepath>and <filepath>iic_channel.h</filepath> for
more details on these APIs. </note> </p> </section>
<section id="GUID-7A8667A0-6061-446C-AE93-6BD3E0DB4952"><title>Implementation
details</title><p>You must next read:<ul>
<li><p><xref href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita">IIC
SHAI Implementation Layer: Generic Considerations</xref></p></li>
<li><p><xref href="GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84.dita">IIC
SHAI Implementation Layer: Master Channel</xref></p></li>
<li><p><xref href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita">IIC
SHAI Implementation Layer: Slave Channel</xref></p></li>
</ul></p><p/></section>
</conbody><related-links>
<link href="GUID-C661BFA4-6C39-476A-8DE0-08E18AA0F548.dita"><linktext>IIC
Overview</linktext></link>
<link href="GUID-CB0FC4F4-6DAB-4ADD-B044-0E8B9365B4D5.dita"><linktext>IIC
Concepts Overview</linktext></link>
</related-links></concept>