IIC Implementation Guide

This document describes the overview of how to implement the IIC +platform service APIs and directs you to more specific documentation.

Purpose

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),.

Intended Audience:

This document is intended for +hardware device implementers who want to write adaptation software +to use their specific serial bus hardware with IIC.

Background

There are two main forms of IIC operation:

Master operation
Slave mode

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.

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.

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.

The +IIC platform service API

The IicBus 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 DIicBusChannelMaster, DIicBusChannelSlave and DIicBusChannelMasterSlave classes.

A summary of methods in the IicBus class are :

+ + + +

Method

Purpose

+ + +

QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction)

Queues a transaction for synchronous completion.

+ + +

QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, +TIicBusCallback* aCallback)

Queues a transaction for asynchronous completion.

+ + +

CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction)

Cancels a previously queued transaction (if the transaction +was queued asynchronously).

+ + +

CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* +aCallback, TInt& aChannelId, TBool aAsynch=EFalse)

Capture a slave channel.

The aAsynch parameter indicates +if this is to be done synchronously or asynchronously. The default +is synchronous.

+ + +

ReleaseChannel(TInt aChannelId)

Release a previously captured Slave channel.

+ + +

RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 +aBufGranularity, TInt8 aNumWords, TInt8 aOffset)

+ + +

RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 +aBufGranularity, TInt8 aNumWords, TInt8 aOffset)

+ + +

SetNotificationTrigger(TInt aChannelId, TInt aTrigger)

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.

+ + +

StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, +TAny* aParam2)

Interface to provide extended functionality.

+ + + +

The platform service APIs for controller-less operation +are almost exactly the same, but with the addition of channel constructors +and destructors. Please refer to iic.h, iic_channel.cppand iic_channel.h for +more details on these APIs.

Implementation +details

You must next read:

IIC +SHAI Implementation Layer: Generic Considerations
IIC +SHAI Implementation Layer: Master Channel
IIC +SHAI Implementation Layer: Slave Channel