|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <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> |
|
13 <p>IIC is a an abstraction of serial inter-IC buses such as I2C and |
|
14 SPI. It allows serial bus device drivers to be written that do not |
|
15 need to know the specifics of the underlying hardware technology.</p> |
|
16 <section id="GUID-F9D5DC69-0BFA-42AE-9044-678AAED780A2"><title>Serial |
|
17 inter-IC buses</title> <p>Serial inter-chip buses are a class of bus |
|
18 used to transmit data between components of a hardware system. Examples |
|
19 are: </p> <ul> |
|
20 <li id="GUID-AF4E3C14-BA37-5028-A66E-0C2481A68E7E"><p>I2C,</p> </li> |
|
21 <li id="GUID-D5633729-DFD4-5E03-BC1B-F2EE13223E02"><p>SPI</p> </li> |
|
22 <li id="GUID-E33F3C5F-D824-5B09-BB55-BCE3A3D068BC"><p>SMBus </p> </li> |
|
23 <li id="GUID-3ED0A9E8-FEB7-5707-9782-1307E930A124"><p>Microwire</p> </li> |
|
24 <li id="GUID-56521027-9D91-5640-9BEF-8513B1B8290B"><p>SCCB</p> </li> |
|
25 <li id="GUID-7ABB6B44-F37E-5DCC-84D4-FD0ED6A1993D"><p>CCI. </p> </li> |
|
26 </ul> <p>These buses are commonly used to transmit commands, control-signals |
|
27 and non time-critical data though other, time-critical, uses are possible. |
|
28 The IIC API is used by developers creating client applications, typically |
|
29 device drivers. </p> </section> |
|
30 <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 |
|
31 inter-IC buses. These buses allow for the exchange of commands and |
|
32 simple non time-critical data between devices (nodes) in a bus configuration. |
|
33 IIC is not designed for high-bandwidth data transfer. IIC is not a |
|
34 bus, but a set of functions and concepts so that device drivers can |
|
35 be written that are independent of the chip-specific implementation |
|
36 of each bus type. The Platform Independent Layer (PIL) specifies and |
|
37 implements the functions that are available to device drivers and |
|
38 the SHAI implementation layer implements any parts of the IIC functions |
|
39 that are hardware dependent.</p><p><b>Bus</b></p><p>A bus, in this |
|
40 case a serial bus, is effectively one or more wires along which data |
|
41 or clock signals can be sent. More than one device/node can be attached |
|
42 to a bus. This means that the data on the bus must identify which |
|
43 node should receive that data. One node will be designated as the |
|
44 master node which is responsible for initiating and terminating the |
|
45 data transfer on the bus. See below for more on nodes, master and |
|
46 slave nodes, configuring the bus etc.</p><p><b>Clients</b></p><p>Clients |
|
47 are applications/device drivers that use IIC to send commands and |
|
48 basic data over a serial bus. Clients are typically device drivers |
|
49 for devices such as digitizers, a built-in camera or the real time |
|
50 clock.</p><p><b>Nodes</b></p><p>Each device on the serial bus is a |
|
51 node. A particular node can send or receive commands and data, or |
|
52 can both send and receive commands and data. On each bus, one of the |
|
53 nodes is going to be the phone/handset device which is the one our |
|
54 device driver will be using to send commands onto the bus and to receive |
|
55 commands from the bus.</p><p><b>Master</b> - a serial bus node that |
|
56 is always responsible for initiating and terminating the exchange |
|
57 of commands/data and for synchronizing the data transfer (clocking). |
|
58 A master node acts on behalf of clients of this bus. For example, |
|
59 if a client wants to send commands down a serial bus to a device, |
|
60 the device driver will request that the master initiate the command |
|
61 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 |
|
62 the control of the master node. A number of slave nodes can be present |
|
63 on a single bus. Only one slave node can be addressed by a master |
|
64 at one time. A slave must be addressed by a master before it is allowed |
|
65 to transmit on the bus. A slave is usually associated with one or |
|
66 more functions. Slave nodes sometimes drive the bus but only in response |
|
67 to instructions from the master. </p><p>The role of master may be |
|
68 exchanged between nodes. For example, in I2C, one or more nodes can |
|
69 perform the role of a master, but only one can be the active master |
|
70 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"> |
|
71 <title> An example of a serial bus (I2C) SCL=Serial CLock, |
|
72 SDA=Serial DAta </title> |
|
73 <image href="GUID-B0FA9741-CB42-560F-A13E-78FAA57F7871_d0e93088_href.png" placement="inline"/> |
|
74 </fig><b>Transactions and transfers</b><p>A <b>Transfer</b> is defined |
|
75 as single exchange involving data flowing in one direction From the |
|
76 master to a slave, or slave to master.</p><p>A <b>Transaction</b> comprises |
|
77 a list of transfers, in both directions.</p><p>A basic transaction |
|
78 is half duplex (transfers in both directions, but only one at a time). </p><p>Full duplex (simultaneous transfers in both directions) are enabled |
|
79 for buses that support them, such as SPI.</p><p>A transaction is a |
|
80 synchronous operation and takes control of the bus until the list |
|
81 of transfers in that transaction is complete. However the client can |
|
82 start the transaction with a synchronous call (waits for it to complete) |
|
83 or with an asynchronous call (client thread continues while the transaction |
|
84 is processed. At the end of the transaction a callback function is |
|
85 called to inform the client that the transaction is complete.)</p> </section> |
|
86 <section id="GUID-98FE3AD9-47EB-4525-9B21-8B477C3F5E60"><title>Transaction |
|
87 detail</title><p>A master node initiates a transaction by addressing |
|
88 a slave node, this establishes the two ends of the transaction. The |
|
89 transaction continues with data being exchanged in either direction. |
|
90 The transaction is explicitly terminated by the Master.</p><p>Transactions |
|
91 may be executed either synchronously, or asynchronously. </p><p>Asynchronous |
|
92 execution requires the client to provide a callback. The client must |
|
93 wait for the callback to be executed before accessing the transaction’s |
|
94 objects (buffers, transfers and the transaction itself). </p><p>For |
|
95 synchronous execution, the client thread is blocked until the transaction |
|
96 processing is complete. This means that the client may access the |
|
97 transaction’s objects as soon as the client thread resumes.</p><p><b>Transaction Preamble </b></p><p>The transaction preamble is an |
|
98 optional client-supplied function that is called just before a transaction |
|
99 takes place.</p><p>For example, the transaction preamble may perform |
|
100 a hardware operation required on the slave device in order for it |
|
101 to handle the transaction. This could be selecting a function on a |
|
102 multi-function device, or selecting a set of internal registers.</p><p>The client-supplied transaction preamble function shall not: </p><ul> |
|
103 <li><p>Spin.</p></li> |
|
104 <li><p>Block or wait on a fast mutex.</p></li> |
|
105 <li><p>Use any kernel or base port service that does any of the above. |
|
106 For example, alloc/free memory, signal a DMutex, complete a request, |
|
107 access user side memory.</p></li> |
|
108 </ul></section> |
|
109 <section id="GUID-D93E1A25-278B-4F8B-BA6B-8C5BE8FBC8B9"><title>Extended/multiple |
|
110 transactions</title><p>An extended/multiple transaction (“multitransaction”) |
|
111 is formed from a chain of transactions, and appears to the client |
|
112 to be a single high-level transaction. An extended transaction should |
|
113 be used when the amount of data that is to be transferred (how many |
|
114 transfers) is not known in advance.</p><p>The next transfer in the |
|
115 chain is selected by the Extended Transaction callback. The transaction |
|
116 may be dynamically composed so that additional transfers are added |
|
117 to the transaction while transfers closer to the start of the transaction |
|
118 are being processed.</p><p>For example, an extended transaction could |
|
119 consist of a write transaction followed by a number of read transactions. |
|
120 The reason for making this a single extended transaction is that it |
|
121 prevents other clients performing a read transaction after the initial |
|
122 write transaction and so stealing the data that the client is expecting. |
|
123 Another example is where the multiple transaction consists of a read |
|
124 operation followed by several write operations. If another client |
|
125 can write data after the read, then the slave buffer may not have |
|
126 room for the subsequent write operations.</p></section> |
|
127 <section id="GUID-EC6854E7-CD55-4C0D-8F58-A4A4509ED0F2"><title>Channels</title><p>An applications’ ASIC may support a number of bus modules of different |
|
128 interface standards. Each bus module for a given interface standard |
|
129 may support more than one physical connection. For example, a particular |
|
130 ASIC might have two I2C physical connections and one SPI physical |
|
131 connection. So to set the master node on one of the I2C connections, |
|
132 it must be possible to identify which physical bus to use, which is |
|
133 done by allocating a 'channel number' to a particular node on each |
|
134 connection. That node is the one that IIC controller or device driver |
|
135 talks to.</p><p>The SHAI implementation layer for each bus standard |
|
136 (I2C, SPI etc.) assigns unique channel number identifiers.</p><fig id="GUID-B6CF82C8-543A-4D44-B37B-1263271F3E3A"> |
|
137 <title>Channels</title> |
|
138 <image href="GUID-7B0BA327-54A0-4908-B8E3-0C82112EB957_d0e93167_href.png" placement="inline"/> |
|
139 </fig><title>IIC Controller</title><p>The IIC controller keeps track |
|
140 of the channels. When a client wants to send a command to a particular |
|
141 piece of hardware/function (a node), it asks the controller and passes |
|
142 the channel ID. The controller checks that the operation is allowed |
|
143 and forwards the request to the channel. Or rejects the command if |
|
144 it is not allowed. For example, if a slave operation is requested |
|
145 on a master channel.</p><p>For application processors that possess |
|
146 IIC channels which may be used in a shared manner, the controller |
|
147 provides functionality to negotiate access between simultaneous requests |
|
148 from a number of clients device drivers. </p><fig id="GUID-A2283D71-6EF6-4D8B-92FC-E01F686BEAE0"> |
|
149 <title>Using a controller</title> |
|
150 <image href="GUID-F67AFC0F-5245-48DE-8901-79461FB6EADE_d0e93180_href.png" placement="inline"/> |
|
151 </fig></section> |
|
152 <section id="GUID-0F4E2E98-95CE-4571-BE9E-2A5115FA9D01"><title>Controller-less |
|
153 (Standalone channel) operation</title><p>If a channel is intended |
|
154 to be dedicated to a single client, the controller is not necessary. |
|
155 In this case, the client device driver can access the channel interface |
|
156 directly. The channel is created and maintained by the client, independently |
|
157 of the IIC controller.</p><fig id="GUID-4825FFFC-C5C1-4CEF-919F-0AA1C0B87C00"> |
|
158 <title>Controller-less operation</title> |
|
159 <image href="GUID-690F943E-7459-4FBA-B33C-258969D7759A_d0e93193_href.png" placement="inline"/> |
|
160 </fig></section> |
|
161 <section id="GUID-788A1BB3-4BE9-480B-8437-F63C6F7DB4C9"><title>Transfers |
|
162 and transactions - detail</title> <p><b>Transfers</b> </p> <p>A transfer |
|
163 is implemented as a buffer containing the data to be transmitted and |
|
164 information used to carry out the transmission, including </p> <ul> |
|
165 <li id="GUID-470A0457-9F31-58CA-9D69-CE53C1B12448"><p>the direction |
|
166 of transmission (read or write from the point of view of the master |
|
167 node), </p> </li> |
|
168 <li id="GUID-4BFDA50E-4984-52CA-B2BA-E83E2F88B8C7"><p>the granularity |
|
169 of the buffer (the width of the words in bits), and </p> </li> |
|
170 <li id="GUID-E280D0B2-8FB8-50BF-B49C-3C6EBE6AEF2D"><p>a pointer to |
|
171 the next buffer, used when transfers are combined into transactions |
|
172 as a linked list. </p> </li> |
|
173 </ul> <p>The buffer is implemented with an 8 bit boundary but the |
|
174 data being exchanged may be differently structured. The potential |
|
175 conflict is tackled by the configuration mechanism. </p> <p><b>Transactions</b> </p> <p>A transaction is a sequence of transfers implemented as |
|
176 a linked list. This is why transfers have pointers to transfers. Transactions |
|
177 are of two types. </p> <ul> |
|
178 <li id="GUID-3BB4BEB4-16D8-53C7-A407-E10ED7F9B71A"><p>Unidirectional |
|
179 transactions are a sequence of transfers, either all of them read |
|
180 or all of them write. </p> </li> |
|
181 <li id="GUID-6AEF8C6D-F6EA-51BB-B283-1FC5B81758A5"><p>Combined transactions |
|
182 are a sequence of transfers, some of them read and the others write. </p> </li> |
|
183 </ul> <p>Some buses support duplex transmission, which is simultaneous |
|
184 transfers of data in each direction. The transfers within a transaction |
|
185 take place sequentially, never simultaneously, so that a combined |
|
186 transaction is only ever in half duplex mode. However, it is possible |
|
187 to use the full duplex capabilities of a bus by performing two transactions |
|
188 at the same time. The simplest case of this is two unidirectional |
|
189 transactions in opposite directions. It is also possible to interleave |
|
190 two combined transactions, matching the read and write transfers of |
|
191 each transaction to create a full duplex combined transaction. The |
|
192 IIC platform service API supports this functionality but implementation |
|
193 is a matter for client writers. </p> </section> |
|
194 <section id="GUID-673F7E28-03DF-4C1D-B587-AD72635EB235"><title>Triggers |
|
195 and callbacks</title> <p>A callback is a function to be executed after |
|
196 a transaction in response to a condition called a trigger. A callback |
|
197 is supplied with the result of the information transmitted. Callbacks |
|
198 are of two kinds, master and slave. </p> <p>When the client is master, |
|
199 a master callback runs on completion of an asynchronous transaction |
|
200 request (synchronous master transaction requests do not have callbacks). |
|
201 Its purpose is to notify the client of completion since the client |
|
202 will have been performing other tasks during the transaction. </p> <p>A second kind of master callback is a function called just before |
|
203 a master transaction. The Symbian platform name for a callback of |
|
204 this kind is 'preamble'. </p> <p>Multitransactions may also be associated |
|
205 with master callbacks and preambles. </p> <p>Slave callbacks are issued |
|
206 during a transaction. Since slave channels are mainly reactive, they |
|
207 need to be told what to do on receipt of each individual transfer, |
|
208 and this is the purpose of a slave callback. A slave callback object |
|
209 contains more information than a master callback because a slave channel |
|
210 requires more information in order to proceed with a transfer. The |
|
211 information packaged with a slave callback includes: </p> <ul> |
|
212 <li id="GUID-FF1A42B7-F94D-5482-81B1-C256E2627FDC"><p>the Id of the |
|
213 channel and a pointer to the channel object (which contains the actual |
|
214 function to be called), </p> </li> |
|
215 <li id="GUID-3B57A5D5-4CF7-5572-B74D-E9730B7BDF9E"><p>a pointer to |
|
216 the parameters to be passed to the callback function, </p> </li> |
|
217 <li id="GUID-F671AA96-84DC-559D-9DC6-3A87EFE34B04"><p>the trigger, </p> </li> |
|
218 <li id="GUID-208B21BA-A1C0-5634-B58C-F4905A950CA0"><p>the number of |
|
219 words to be transmitted, and </p> </li> |
|
220 <li id="GUID-CF11B5F7-5A8F-5C33-A39C-5BA6FEFD9DF1"><p>the number of |
|
221 words to be received. </p> </li> |
|
222 </ul> </section> |
|
223 <section id="GUID-21F8D5E4-5648-4B23-A4A5-EA1B2933912D"><title>Use |
|
224 of the bus API</title> <p>Client applications use the platform service |
|
225 API to communicate with an IIC bus. The bus API consists of a class |
|
226 representing a bus and contains two sets of functions, the master |
|
227 side API used when the client is talking to a master channel, and |
|
228 the slave side API used when the client is talking to a slave channel. |
|
229 A MasterSlave channel provides both sets of functions but returns |
|
230 an error if a master function is used while the channel is in slave |
|
231 mode, and similarly returns an error if a slave function is used when |
|
232 the channel is in master mode.</p> <p>A client application of a master |
|
233 channel may use the functions of a number of devices on the same bus. |
|
234 A client may also talk to multiple buses over multiple channels. A |
|
235 master channel can also be shared between multiple clients. </p> <p>The master side API provides functionality to: </p> <ul> |
|
236 <li id="GUID-6B62796A-4B54-50E6-A104-CB51369C1126"><p>queue transactions |
|
237 synchronously, </p> </li> |
|
238 <li id="GUID-5D0D76BB-49EE-5176-B998-A2DCD8253043"><p>queue transactions |
|
239 asynchronously, and </p> </li> |
|
240 <li id="GUID-AE1F7A2B-04AD-521E-98E2-0E7CFD21024D"><p>cancel asynchronous |
|
241 transactions. </p> </li> |
|
242 </ul> <p>Slave nodes operate at the level of the transfer, not the |
|
243 transaction, and must be told what channel and buffer to use. They |
|
244 act in response to slave callbacks. </p> <p>The slave side API provides |
|
245 functionality to: </p> <ul> |
|
246 <li id="GUID-AEE022D0-05C9-57D4-887B-B0B0EDD13694"><p>capture a channel, </p> </li> |
|
247 <li id="GUID-BD58A640-F61C-5CBA-8743-876A1FF0B4DA"><p>release a channel, </p> </li> |
|
248 <li id="GUID-E1F4CE98-E6CF-5AFF-A287-DEAF87BFFBDD"><p>register a receive |
|
249 buffer, </p> </li> |
|
250 <li id="GUID-5B1A90FE-FAB0-5BFA-BAB8-C124D4478BA7"><p>register a transmit |
|
251 buffer, and </p> </li> |
|
252 <li id="GUID-A44525D9-0FB3-5EFF-B233-D6EC3C78CD69"><p>specify a trigger |
|
253 which starts the next transfer. </p> </li> |
|
254 </ul> <p>A channel may also be a MasterSlave channel. A MasterSlave |
|
255 channel enters either master mode or slave mode when certain entry |
|
256 conditions are fulfilled and continues in that mode until certain |
|
257 exit conditions are fulfilled. A MasterSlave channel can never operate |
|
258 in both modes simultaneously. </p> <p>A MasterSlave channel enters |
|
259 master mode as soon as a transaction is queued. It continues in master |
|
260 mode until all transactions are completed and then exits master mode. |
|
261 While in master mode it accepts no slave API calls. </p> <p>A MasterSlave |
|
262 channel enters slave mode when a client captures the channel. It continues |
|
263 in slave mode until the channel is released and then exits slave mode. |
|
264 While in slave mode it accepts no master API calls. </p> <p>The master |
|
265 and slave side APIs both also supply a static extension used by developers |
|
266 to provide additional functionality. </p> </section> |
|
267 <section id="GUID-9DF689AD-5FA8-4EA0-8F1C-007EA2F5FEF2"><title>Configuration |
|
268 of bus, transaction and device</title> <p>The proprietary variants |
|
269 of IIC technology and the different devices which they support require |
|
270 configuration at the level of the bus and the node. Bus configuration |
|
271 is static and node configuration dynamic. </p> <p>The static configuration |
|
272 of the bus is specified at design time and executed at build time. |
|
273 It involves designating nodes as master or slave and assigning addresses |
|
274 to nodes. The IIC performance service API encapsulates the bus configuration |
|
275 as a single structured integer called the <codeph>bus ID</codeph> whose |
|
276 value is set using bit masks representing individual configuration |
|
277 parameters. </p> <p>The dynamic configuration of the nodes is performed |
|
278 by the clients. Each client configures its channel at the start of |
|
279 a transaction, setting parameters relating to the physical node and |
|
280 to the transaction: speed, endianness, word length and so on. </p> </section> |
|
281 <section id="GUID-B7C1E9D9-6C27-42E3-A769-EBE38A00C110"><title>Timers</title><p>There are two timers that must be implemented in the SHAI implementation |
|
282 layer:<ul> |
|
283 <li><p>Client Timeout</p></li> |
|
284 <li><p>Master Timeout</p></li> |
|
285 </ul></p><p><b>Client timeout</b> - specifies how long to wait for |
|
286 the client to respond to bus events, such as data received, before |
|
287 telling the SHAI implementation layer to cancel the transaction.</p><p><b>Master timeout</b> - specifies how long to wait for the master |
|
288 to perform the next transfer in the transaction. If this timer runs |
|
289 out, then terminate the transaction by calling the PIL <codeph>NotifyClient()</codeph> which will inform both the client and the SHAI implementation layer |
|
290 that the transaction is aborted.</p></section> |
|
291 </conbody><related-links> |
|
292 <link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client |
|
293 of Master Channel Tutorial</linktext></link> |
|
294 <link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client |
|
295 of Slave Channel Tutorial</linktext></link> |
|
296 <link href="GUID-99FC067C-0AED-5373-AF63-8DB7FF5C1F7E.dita"><linktext>SPI |
|
297 Technology Guide</linktext></link> |
|
298 </related-links></concept> |