<?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-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239" xml:lang="en"><title>IIC SHAI Implementation Layer: Generic Considerations</title><shortdesc>This document explains how to implement the SHAI implementation
layer for IIC.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-C3EE341A-BEAB-4E0C-A91E-7A1A285BCE96"><title>Purpose</title> <p>This document covers information which is generic to master and
slave channel implementation </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-38B543E8-06DB-417F-8B8E-84F6B43DF8BF"><title>Generic
architecture</title> <p>Different IIC buses have a large amount of
functionality in common, but some functionality is specific to individual
implementations. For this reason, the IIC software has an architecture
consisting of two layers, the Platform Independent Layer (PIL) and
the SHAI implementation layer. The Platform Independent Layer is a
set of classes which encapsulate generic functionality and have been
implemented for you. The SHAI implementation layer is an interface
which you must implement yourself to encapsulate the functionality
specific to the platform you are working on. </p> <p>You implement
the SHAI implementation layer by subclassing the classes of the Platform
Independent Layer and writing functions that provide an abstraction
of your hardware. To access the hardware you are strongly recommended
to use existing Symbian APIs such as e.g. <codeph>AsspRegister</codeph> to access hardware registers, or <codeph>GPIO</codeph> to access
GPIO pins). </p> <p>An IIC channel operates in one of two modes, master
and slave, and there are separate master and slave APIs to be implemented.
In master mode, a channel and a client communicating with that channel
execute in two separate threads. In slave mode there is only one thread
for both channel and client. </p> <p>The SHAI implementation and platform
independent APIs assume an interrupt-driven approach to implementation.
An event on hardware triggers an interrupt, which then signals this
event to the channel thread (where client is master) or client thread
(where client is slave). This means that implementation involves writing
interrupt service routines (ISRs) and a DFC queue to hold the callbacks
which respond to them. For both master and slave operation, the callbacks
are queued for execution on the client thread - so the client thread
must not be blocked, otherwise the callbacks will never run.</p><p>Clients of a master channel request transactions for execution in
either a synchronous or asynchronous manner. This results in the transaction
being entered in the channel’s request queue.  </p><p>If synchronous
execution is requested, the client thread is blocked until the transaction
completes (either an ISR or polling mechanism in the SHAI implementation
layer recognizes the transaction has completed, and it calls the PIL
method <codeph>CompleteRequest()</codeph>, which will unblock the
client thread.  </p><p>If asynchronous execution is requested, the
client thread is not blocked, and may continue to perform other tasks.
In the meanwhile, the channel thread will retrieve the next transaction
from the request queue and pass it to the SHAI implementation layer
for processing. When the transaction completes, the SHAI implementation
layer calls the PIL method <codeph>CompleteRequest()</codeph> and
this adds the client’s callback to the client’s DFC queue.  </p><p>A client of a slave channel provides receive and transmit buffers
to be used and specifies the types of event (trigger) that it wishes
to be notified of. When ANY event occurs, the SHAI implementation
layer should call the PIL method <codeph>NotifyClient()</codeph>;
this determines whether the reported triggers qualify for notifying
the client – if so, the client callback is added to the client’s DFC
queue for execution. Note that the same mechanism is used to notify
the client of completion of asynchronous capture of the channel, and
of bus errors.</p> <p>You should refer to the template port at <filepath>\os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic</filepath> for more information. </p> </section>
</conbody><related-links>
<link href="GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84.dita"><linktext>IIC
SHAI Implementation Layer: Master Channel</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>