<?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-B2F86F54-EF50-56DB-ADF7-15325AC9324D" xml:lang="en"><title>IIC Concepts</title><shortdesc>This document provides an overview of IIC concepts. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>IIC is a an abstraction of serial inter-IC buses such as I2C and
SPI. It allows serial bus device drivers to be written that do not
need to know the specifics of the underlying hardware technology.</p>
<section id="GUID-F9D5DC69-0BFA-42AE-9044-678AAED780A2"><title>Serial
inter-IC buses</title> <p>Serial inter-chip buses are a class of bus
used to transmit data between components of a hardware system. Examples
are: </p> <ul>
<li id="GUID-AF4E3C14-BA37-5028-A66E-0C2481A68E7E"><p>I2C,</p> </li>
<li id="GUID-D5633729-DFD4-5E03-BC1B-F2EE13223E02"><p>SPI</p> </li>
<li id="GUID-E33F3C5F-D824-5B09-BB55-BCE3A3D068BC"><p>SMBus </p> </li>
<li id="GUID-3ED0A9E8-FEB7-5707-9782-1307E930A124"><p>Microwire</p> </li>
<li id="GUID-56521027-9D91-5640-9BEF-8513B1B8290B"><p>SCCB</p> </li>
<li id="GUID-7ABB6B44-F37E-5DCC-84D4-FD0ED6A1993D"><p>CCI. </p> </li>
</ul> <p>These buses are commonly used to transmit commands, control-signals
and non time-critical data though other, time-critical, uses are possible.
The IIC API is used by developers creating client applications, typically
device drivers. </p> </section>
<section id="GUID-E67D9AC2-DD3D-48FD-9E48-B79BC73FFE6A-GENID-1-2-1-10-1-5-1-6-1-1-6-1-3-1-3-3"><title>Concepts</title>             <p><b>IIC</b></p><p>IIC provides an abstraction of serial
inter-IC buses. These buses allow for the exchange of commands and
simple non time-critical data between devices (nodes) in a bus configuration.
IIC is not designed for high-bandwidth data transfer. IIC is not a
bus, but a set of functions and concepts so that device drivers can
be written that are independent of the chip-specific implementation
of each bus type. The Platform Independent Layer (PIL) specifies and
implements the functions that are available to device drivers and
the SHAI implementation layer implements any parts of the IIC functions
that are hardware dependent.</p><p><b>Bus</b></p><p>A bus, in this
case a serial bus, is effectively one or more wires along which data
or clock signals can be sent. More than one device/node can be attached
to a bus. This means that the data on the bus must identify which
node should receive that data. One node will be designated as the
master node which is responsible for initiating and terminating the
data transfer on the bus. See below for more on nodes, master and
slave nodes, configuring the bus etc.</p><p><b>Clients</b></p><p>Clients
are applications/device drivers that use IIC to send commands and
basic data over a serial bus. Clients are typically device drivers
for devices such as digitizers, a built-in camera or the real time
clock.</p><p><b>Nodes</b></p><p>Each device on the serial bus is a
node. A particular node can send or receive commands and data, or
can both send and receive commands and data. On each bus, one of the
nodes is going to be the phone/handset device which is the one our
device driver will be using to send commands onto the bus and to receive
commands from the bus.</p><p><b>Master</b> - a serial bus node that
is always responsible for initiating and terminating the exchange
of commands/data and for synchronizing the data transfer (clocking).
A master node acts on behalf of clients of this bus. For example,
if a client wants to send commands down a serial bus to a device,
the device driver will request that the master initiate the command
transfer. One node on each bus must perform the role of Master.</p><p><b>Slave</b> - each slave node sends or receives commands under
the control of the master node. A number of slave nodes can be present
on a single bus. Only one slave node can be addressed by a master
at one time. A slave must be addressed by a master before it is allowed
to transmit on the bus. A slave is usually associated with one or
more functions. Slave nodes sometimes drive the bus but only in response
to instructions from the master. </p><p>The role of master may be
exchanged between nodes. For example, in I2C, one or more nodes can
perform the role of a master, but only one can be the active master
at any one time. In IIC. this is supported by a ‘<b>MasterSlave</b>’ type, which can alternate the two roles.</p> <fig id="GUID-E7B96ED2-9814-5B75-8051-48337121F985-GENID-1-2-1-10-1-5-1-6-1-1-6-1-3-1-3-3-13">
<title>             An example of a serial bus (I2C)  SCL=Serial CLock,
SDA=Serial DAta      </title>
<image href="GUID-B0FA9741-CB42-560F-A13E-78FAA57F7871_d0e93088_href.png" placement="inline"/>
</fig><b>Transactions and transfers</b><p>A <b>Transfer</b> is defined
as single exchange involving data flowing in one direction From the
master to a slave, or slave to master.</p><p>A <b>Transaction</b> comprises
a list of transfers, in both directions.</p><p>A basic transaction
is half duplex (transfers in both directions, but only one at a time). </p><p>Full duplex (simultaneous transfers in both directions) are enabled
for buses that support them, such as SPI.</p><p>A transaction is a
synchronous operation and takes control of the bus until the list
of transfers in that transaction is complete. However the client can
start the transaction with a synchronous call (waits for it to complete)
or with an asynchronous call (client thread continues while the transaction
is processed. At the end of the transaction a callback function is
called to inform the client that the transaction is complete.)</p>        </section>
<section id="GUID-98FE3AD9-47EB-4525-9B21-8B477C3F5E60"><title>Transaction
detail</title><p>A master node initiates a transaction by addressing
a slave node, this establishes the two ends of the transaction. The
transaction continues with data being exchanged in either direction.
The transaction is explicitly terminated by the Master.</p><p>Transactions
may be executed either synchronously, or asynchronously. </p><p>Asynchronous
execution requires the client to provide a callback. The client must
wait for the callback to be executed before accessing the transaction’s
objects (buffers, transfers and the transaction itself). </p><p>For
synchronous execution, the client thread is blocked until the transaction
processing is complete. This means that the client may access the
transaction’s objects as soon as the client thread resumes.</p><p><b>Transaction Preamble </b></p><p>The transaction preamble is an
optional client-supplied function that is called just before a transaction
takes place.</p><p>For example, the transaction preamble may perform
a hardware operation required on the slave device in order for it
to handle the transaction. This could be selecting a function on a
multi-function device, or selecting a set of internal registers.</p><p>The client-supplied transaction preamble function shall not: </p><ul>
<li><p>Spin.</p></li>
<li><p>Block or wait on a fast mutex.</p></li>
<li><p>Use any kernel or base port service that does any of the above.
For example, alloc/free memory, signal a DMutex, complete a request,
access user side memory.</p></li>
</ul></section>
<section id="GUID-D93E1A25-278B-4F8B-BA6B-8C5BE8FBC8B9"><title>Extended/multiple
transactions</title><p>An extended/multiple transaction (“multitransaction”)
is formed from a chain of transactions, and appears to the client
to be a single high-level transaction. An extended transaction should
be used when the amount of data that is to be transferred (how many
transfers) is not known in advance.</p><p>The next transfer in the
chain is selected by the Extended Transaction callback. The transaction
may be dynamically composed so that additional transfers are added
to the transaction while transfers closer to the start of the transaction
are being processed.</p><p>For example, an extended transaction could
consist of a write transaction followed by a number of read transactions.
The reason for making this a single extended transaction is that it
prevents other clients performing a read transaction after the initial
write transaction and so stealing the data that the client is expecting.
Another example is where the multiple transaction consists of a read
operation followed by several write operations. If another client
can write data after the read, then the slave buffer may not have
room for the subsequent write operations.</p></section>
<section id="GUID-EC6854E7-CD55-4C0D-8F58-A4A4509ED0F2"><title>Channels</title><p>An applications’ ASIC may support a number of bus modules of different
interface standards. Each bus module for a given interface standard
may support more than one physical connection. For example, a particular
ASIC might have two I2C physical connections and one SPI physical
connection. So to set the master node on one of the I2C connections,
it must be possible to identify which physical bus to use, which is
done by allocating a 'channel number' to a particular node on each
connection. That node is the one that IIC controller or device driver
talks to.</p><p>The SHAI implementation layer for each bus standard
(I2C, SPI etc.) assigns unique channel number identifiers.</p><fig id="GUID-B6CF82C8-543A-4D44-B37B-1263271F3E3A">
<title>Channels</title>
<image href="GUID-7B0BA327-54A0-4908-B8E3-0C82112EB957_d0e93167_href.png" placement="inline"/>
</fig><title>IIC Controller</title><p>The IIC controller keeps track
of the channels. When a client wants to send a command to a particular
piece of hardware/function (a node), it asks the controller and passes
the channel ID. The controller checks that the operation is allowed
and forwards the request to the channel. Or rejects the command if
it is not allowed. For example, if a slave operation is requested
on a master channel.</p><p>For application processors that possess
IIC channels which may be used in a shared manner, the controller
provides functionality to negotiate access between simultaneous requests
from a number of clients device drivers. </p><fig id="GUID-A2283D71-6EF6-4D8B-92FC-E01F686BEAE0">
<title>Using a controller</title>
<image href="GUID-F67AFC0F-5245-48DE-8901-79461FB6EADE_d0e93180_href.png" placement="inline"/>
</fig></section>
<section id="GUID-0F4E2E98-95CE-4571-BE9E-2A5115FA9D01"><title>Controller-less
(Standalone channel) operation</title><p>If a channel is intended
to be dedicated to a single client, the controller is not necessary.
In this case, the client device driver can access the channel interface
directly. The channel is created and maintained by the client, independently
of the IIC controller.</p><fig id="GUID-4825FFFC-C5C1-4CEF-919F-0AA1C0B87C00">
<title>Controller-less operation</title>
<image href="GUID-690F943E-7459-4FBA-B33C-258969D7759A_d0e93193_href.png" placement="inline"/>
</fig></section>
<section id="GUID-788A1BB3-4BE9-480B-8437-F63C6F7DB4C9"><title>Transfers
and transactions - detail</title> <p><b>Transfers</b> </p> <p>A transfer
is implemented as a buffer containing the data to be transmitted and
information used to carry out the transmission, including </p> <ul>
<li id="GUID-470A0457-9F31-58CA-9D69-CE53C1B12448"><p>the direction
of transmission (read or write from the point of view of the master
node), </p> </li>
<li id="GUID-4BFDA50E-4984-52CA-B2BA-E83E2F88B8C7"><p>the granularity
of the buffer (the width of the words in bits), and </p> </li>
<li id="GUID-E280D0B2-8FB8-50BF-B49C-3C6EBE6AEF2D"><p>a pointer to
the next buffer, used when transfers are combined into transactions
as a linked list. </p> </li>
</ul> <p>The buffer is implemented with an 8 bit boundary but the
data being exchanged may be differently structured. The potential
conflict is tackled by the configuration mechanism. </p> <p><b>Transactions</b> </p> <p>A transaction is a sequence of transfers implemented as
a linked list. This is why transfers have pointers to transfers. Transactions
are of two types. </p> <ul>
<li id="GUID-3BB4BEB4-16D8-53C7-A407-E10ED7F9B71A"><p>Unidirectional
transactions are a sequence of transfers, either all of them read
or all of them write. </p> </li>
<li id="GUID-6AEF8C6D-F6EA-51BB-B283-1FC5B81758A5"><p>Combined transactions
are a sequence of transfers, some of them read and the others write. </p> </li>
</ul> <p>Some buses support duplex transmission, which is simultaneous
transfers of data in each direction. The transfers within a transaction
take place sequentially, never simultaneously, so that a combined
transaction is only ever in half duplex mode. However, it is possible
to use the full duplex capabilities of a bus by performing two transactions
at the same time. The simplest case of this is two unidirectional
transactions in opposite directions. It is also possible to interleave
two combined transactions, matching the read and write transfers of
each transaction to create a full duplex combined transaction. The
IIC platform service API supports this functionality but implementation
is a matter for client writers. </p> </section>
<section id="GUID-673F7E28-03DF-4C1D-B587-AD72635EB235"><title>Triggers
and callbacks</title> <p>A callback is a function to be executed after
a transaction in response to a condition called a trigger. A callback
is supplied with the result of the information transmitted. Callbacks
are of two kinds, master and slave. </p> <p>When the client is master,
a master callback runs on completion of an asynchronous transaction
request (synchronous master transaction requests do not have callbacks).
Its purpose is to notify the client of completion since the client
will have been performing other tasks during the transaction. </p> <p>A second kind of master callback is a function called just before
a master transaction. The Symbian platform name for a callback of
this kind is 'preamble'. </p> <p>Multitransactions may also be associated
with master callbacks and preambles. </p> <p>Slave callbacks are issued
during a transaction. Since slave channels are mainly reactive, they
need to be told what to do on receipt of each individual transfer,
and this is the purpose of a slave callback. A slave callback object
contains more information than a master callback because a slave channel
requires more information in order to proceed with a transfer. The
information packaged with a slave callback includes: </p> <ul>
<li id="GUID-FF1A42B7-F94D-5482-81B1-C256E2627FDC"><p>the Id of the
channel and a pointer to the channel object (which contains the actual
function to be called), </p> </li>
<li id="GUID-3B57A5D5-4CF7-5572-B74D-E9730B7BDF9E"><p>a pointer to
the parameters to be passed to the callback function, </p> </li>
<li id="GUID-F671AA96-84DC-559D-9DC6-3A87EFE34B04"><p>the trigger, </p> </li>
<li id="GUID-208B21BA-A1C0-5634-B58C-F4905A950CA0"><p>the number of
words to be transmitted, and </p> </li>
<li id="GUID-CF11B5F7-5A8F-5C33-A39C-5BA6FEFD9DF1"><p>the number of
words to be received. </p> </li>
</ul> </section>
<section id="GUID-21F8D5E4-5648-4B23-A4A5-EA1B2933912D"><title>Use
of the bus API</title> <p>Client applications use the platform service
API to communicate with an IIC bus. The bus API consists of a class
representing a bus and contains two sets of functions, the master
side API used when the client is talking to a master channel, and
the slave side API used when the client is talking to a slave channel.
A MasterSlave channel provides both sets of functions but returns
an error if a master function is used while the channel is in slave
mode, and similarly returns an error if a slave function is used when
the channel is in master mode.</p> <p>A client application of a master
channel may use the functions of a number of devices on the same bus.
A client may also talk to multiple buses over multiple channels. A
master channel can also be shared between multiple clients. </p> <p>The master side API provides functionality to: </p> <ul>
<li id="GUID-6B62796A-4B54-50E6-A104-CB51369C1126"><p>queue transactions
synchronously, </p> </li>
<li id="GUID-5D0D76BB-49EE-5176-B998-A2DCD8253043"><p>queue transactions
asynchronously, and </p> </li>
<li id="GUID-AE1F7A2B-04AD-521E-98E2-0E7CFD21024D"><p>cancel asynchronous
transactions. </p> </li>
</ul> <p>Slave nodes operate at the level of the transfer, not the
transaction, and must be told what channel and buffer to use. They
act in response to slave callbacks. </p> <p>The slave side API provides
functionality to: </p> <ul>
<li id="GUID-AEE022D0-05C9-57D4-887B-B0B0EDD13694"><p>capture a channel, </p> </li>
<li id="GUID-BD58A640-F61C-5CBA-8743-876A1FF0B4DA"><p>release a channel, </p> </li>
<li id="GUID-E1F4CE98-E6CF-5AFF-A287-DEAF87BFFBDD"><p>register a receive
buffer, </p> </li>
<li id="GUID-5B1A90FE-FAB0-5BFA-BAB8-C124D4478BA7"><p>register a transmit
buffer, and </p> </li>
<li id="GUID-A44525D9-0FB3-5EFF-B233-D6EC3C78CD69"><p>specify a trigger
which starts the next transfer. </p> </li>
</ul> <p>A channel may also be a MasterSlave channel. A MasterSlave
channel enters either master mode or slave mode when certain entry
conditions are fulfilled and continues in that mode until certain
exit conditions are fulfilled. A MasterSlave channel can never operate
in both modes simultaneously. </p> <p>A MasterSlave channel enters
master mode as soon as a transaction is queued. It continues in master
mode until all transactions are completed and then exits master mode.
While in master mode it accepts no slave API calls. </p> <p>A MasterSlave
channel enters slave mode when a client captures the channel. It continues
in slave mode until the channel is released and then exits slave mode.
While in slave mode it accepts no master API calls. </p> <p>The master
and slave side APIs both also supply a static extension used by developers
to provide additional functionality. </p> </section>
<section id="GUID-9DF689AD-5FA8-4EA0-8F1C-007EA2F5FEF2"><title>Configuration
of bus, transaction and device</title> <p>The proprietary variants
of IIC technology and the different devices which they support require
configuration at the level of the bus and the node. Bus configuration
is static and node configuration dynamic. </p> <p>The static configuration
of the bus is specified at design time and executed at build time.
It involves designating nodes as master or slave and assigning addresses
to nodes. The IIC performance service API encapsulates the bus configuration
as a single structured integer called the <codeph>bus ID</codeph> whose
value is set using bit masks representing individual configuration
parameters. </p> <p>The dynamic configuration of the nodes is performed
by the clients. Each client configures its channel at the start of
a transaction, setting parameters relating to the physical node and
to the transaction: speed, endianness, word length and so on. </p> </section>
<section id="GUID-B7C1E9D9-6C27-42E3-A769-EBE38A00C110"><title>Timers</title><p>There are two timers that must be implemented in the SHAI implementation
layer:<ul>
<li><p>Client Timeout</p></li>
<li><p>Master Timeout</p></li>
</ul></p><p><b>Client timeout</b> - specifies how long to wait for
the client to respond to bus events, such as data received, before
telling the SHAI implementation layer to cancel the transaction.</p><p><b>Master timeout</b> - specifies how long to wait for the master
to perform the next transfer in the transaction. If this timer runs
out, then terminate the transaction by calling the PIL <codeph>NotifyClient()</codeph> which will inform both the client and the SHAI implementation layer
that the transaction is aborted.</p></section>
</conbody><related-links>
<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-99FC067C-0AED-5373-AF63-8DB7FF5C1F7E.dita"><linktext>SPI
Technology Guide</linktext></link>
</related-links></concept>