IIC Concepts

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.

Serial +inter-IC buses

Serial inter-chip buses are a class of bus +used to transmit data between components of a hardware system. Examples +are:

I2C,
SPI
SMBus
Microwire
SCCB
CCI.

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.

Concepts

IIC

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.

Bus

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.

Clients

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.

Nodes

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.

Master - 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.

Slave - 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.

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 ‘MasterSlave’ type, which can alternate the two roles.

+ An example of a serial bus (I2C) SCL=Serial CLock, +SDA=Serial DAta + +Transactions and transfers

A Transfer is defined +as single exchange involving data flowing in one direction From the +master to a slave, or slave to master.

A Transaction comprises +a list of transfers, in both directions.

A basic transaction +is half duplex (transfers in both directions, but only one at a time).

Full duplex (simultaneous transfers in both directions) are enabled +for buses that support them, such as SPI.

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

Transaction +detail

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.

Transactions +may be executed either synchronously, or asynchronously.

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

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.

Transaction Preamble

The transaction preamble is an +optional client-supplied function that is called just before a transaction +takes place.

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.

The client-supplied transaction preamble function shall not:

Spin.
Block or wait on a fast mutex.
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.

Extended/multiple +transactions

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.

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.

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.

Channels

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.

The SHAI implementation layer for each bus standard +(I2C, SPI etc.) assigns unique channel number identifiers.

+Channels + +IIC Controller

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.

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.

+Using a controller + +

Controller-less +(Standalone channel) operation

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.

+Controller-less operation + +

Transfers +and transactions - detail

Transfers

A transfer +is implemented as a buffer containing the data to be transmitted and +information used to carry out the transmission, including

the direction +of transmission (read or write from the point of view of the master +node),
the granularity +of the buffer (the width of the words in bits), and
a pointer to +the next buffer, used when transfers are combined into transactions +as a linked list.

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.

Transactions

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.

Unidirectional +transactions are a sequence of transfers, either all of them read +or all of them write.
Combined transactions +are a sequence of transfers, some of them read and the others write.

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.

Triggers +and callbacks

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.

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.

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'.

Multitransactions may also be associated +with master callbacks and preambles.

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:

the Id of the +channel and a pointer to the channel object (which contains the actual +function to be called),
a pointer to +the parameters to be passed to the callback function,
the trigger,
the number of +words to be transmitted, and
the number of +words to be received.

Use +of the bus API

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.

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.

The master side API provides functionality to:

queue transactions +synchronously,
queue transactions +asynchronously, and
cancel asynchronous +transactions.

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.

The slave side API provides +functionality to:

capture a channel,
release a channel,
register a receive +buffer,
register a transmit +buffer, and
specify a trigger +which starts the next transfer.

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.

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.

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.

The master +and slave side APIs both also supply a static extension used by developers +to provide additional functionality.

Configuration +of bus, transaction and device

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.

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 bus ID whose +value is set using bit masks representing individual configuration +parameters.

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.

Timers

There are two timers that must be implemented in the SHAI implementation +layer:

Client Timeout
Master Timeout

Client timeout - 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.

Master timeout - 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 NotifyClient() which will inform both the client and the SHAI implementation layer +that the transaction is aborted.