|
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-98210124-0B65-4679-BB3A-E94B9999365C" xml:lang="en"><title>IIC Client Interface Guide</title><shortdesc>This document explains how to use the IIC client interface |
|
13 API.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-1C12EB58-E364-4536-A6FB-FFAC4B4AF81E"><title>Introduction</title><p>This guide describes how to use the IIC client interface API.</p></section> |
|
15 <section id="GUID-5C79175E-3193-48B8-8000-7AA20BECD440"><title>Channels</title><p>In this document, a channel is a multi-wire bus with a two or |
|
16 more devices connected to it. At least one of the devices can act |
|
17 as the master.</p></section> |
|
18 <section id="GUID-9CD79528-826C-4433-87C2-4158B4112660"><title>Modes |
|
19 of operation</title><p>There are three possible modes that a device |
|
20 can be in as regards to the IIC client interface API (regardless of |
|
21 the underlying two-wire bus that is being used ):</p><table id="GUID-9CBF7001-A4E1-4A93-B900-444AB06B97A4"> |
|
22 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
23 <thead> |
|
24 <row> |
|
25 <entry valign="top"><p><b>Mode</b></p></entry> |
|
26 <entry valign="top"><p><b>Description</b></p></entry> |
|
27 </row> |
|
28 </thead> |
|
29 <tbody> |
|
30 <row> |
|
31 <entry><p>Master</p></entry> |
|
32 <entry><p>The device is responsible for initializing and terminating |
|
33 the data transfer.</p></entry> |
|
34 </row> |
|
35 <row> |
|
36 <entry><p>Slave</p></entry> |
|
37 <entry><p>The device carries out the transfer initialized by a another |
|
38 device acting as a master.</p></entry> |
|
39 </row> |
|
40 <row> |
|
41 <entry><p>MasterSlave</p></entry> |
|
42 <entry><p>The device can perform both master and slave roles.</p></entry> |
|
43 </row> |
|
44 </tbody> |
|
45 </tgroup> |
|
46 </table></section> |
|
47 <section id="GUID-F04D5138-0B76-425B-AB7F-EAF9B49AE385"><title>Transactions</title><p>A single exchange of data in one direction is known as a transfer.</p><p>A list of transfers is known as a transaction.</p><p>Transactions |
|
48 can be performed in half-duplex, or , full-duplex (if the underlying |
|
49 bus supports it).</p></section> |
|
50 <section id="GUID-4B44C99C-5C16-45DD-BDCE-A275ADFF2EE6"><title>Transaction |
|
51 preamble</title><p>In certain instances, some pre-processing might |
|
52 be required by the devices before a transaction can occur.</p><p>This |
|
53 can be done by the transaction preamble functionality, which executes |
|
54 immediately before the transaction is performed. This takes the form |
|
55 of a function.</p><p><note> the following restrictions apply to this |
|
56 function:</note></p><ul> |
|
57 <li><p>No spin locks are to be used.</p></li> |
|
58 <li><p>There are no block or waiting on a fast mutex operations.</p></li> |
|
59 <li><p>There are no calls to code that either uses spin locks, waits |
|
60 or blocks a fast mutex.</p></li> |
|
61 </ul><p>This is for a device that is in master mode.</p></section> |
|
62 <section id="GUID-254408BF-3797-4E82-B05D-EA8B99CB1EC8"><title>Extended |
|
63 transactions</title><p>This is where a number of separate transactions |
|
64 are linked together. It is used, for example, in situations where |
|
65 it is not known in advance how big the transaction will be. </p><p>This is for a device that is in master mode.</p></section> |
|
66 <section id="GUID-9F62C005-AD6E-4AB3-8481-1834E5C8FB5F"><title>Controller |
|
67 and controller-less operation</title><p>Added to the above functionality, |
|
68 the IIC platform service API has two modes of operation:</p><ul> |
|
69 <li><p>With-controller and</p></li> |
|
70 <li><p>Controller-less</p></li> |
|
71 </ul><p>Controller operation is used in a situation where multiple |
|
72 device drivers can communicate with multiple channels. In controller-less |
|
73 operation, the link between a device driver and a channel is fixed.</p><p>In controller-less operation, the mode of the channel is set at |
|
74 build time, buy using the following macros in the relevant mmp files:</p><table id="GUID-01CC4575-6FCD-446B-AB39-0A97D7E698D2"> |
|
75 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
76 <thead> |
|
77 <row> |
|
78 <entry align="left" valign="top"><p><b>Macro</b></p></entry> |
|
79 <entry align="left" valign="top"><p><b>Description</b></p></entry> |
|
80 </row> |
|
81 </thead> |
|
82 <tbody> |
|
83 <row> |
|
84 <entry><p>MASTER_MODE</p></entry> |
|
85 <entry><p>Specifies that the device is to act as a master.</p></entry> |
|
86 </row> |
|
87 <row> |
|
88 <entry><p>SLAVE_MODE</p></entry> |
|
89 <entry><p>Specifies that the device is to act as a slave.</p></entry> |
|
90 </row> |
|
91 </tbody> |
|
92 </tgroup> |
|
93 </table><fig id="GUID-B72C9F84-4D55-4973-9D97-BD764F4CBBEA"> |
|
94 <title>IIC with-controller operation</title> |
|
95 <image href="GUID-F67AFC0F-5245-48DE-8901-79461FB6EADE_d0e94068_href.png" placement="inline"/> |
|
96 </fig><fig id="GUID-E0227554-01E6-47CE-AA42-B45832D6F36C"> |
|
97 <title>IIC controller-less operation</title> |
|
98 <image href="GUID-3CB74FE6-272E-4176-BC51-E36103CADB09_d0e94075_href.png" placement="inline"/> |
|
99 </fig></section> |
|
100 <section id="GUID-B7D17B8B-78AA-46AE-870B-C848CA2F8B08"><title>Interface |
|
101 classes</title><p>The class that is used for the client interface |
|
102 depends on whether the IIC controller is to be used or not.</p><p>If the IIC Controller is to be used, then the client interface API |
|
103 class is:</p><table id="GUID-DD881644-9306-4900-A66C-5737D487DABE"> |
|
104 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
105 <thead> |
|
106 <row> |
|
107 <entry valign="top"><p><b>Name</b></p></entry> |
|
108 <entry valign="top"><p><b>Description</b></p></entry> |
|
109 </row> |
|
110 </thead> |
|
111 <tbody> |
|
112 <row> |
|
113 <entry><p><xref href="GUID-69949E47-8FDF-3651-BEEF-43726EBEB5FF.dita"><apiname>IicBus</apiname></xref></p></entry> |
|
114 <entry><p>Client interface API for the IIC component.</p></entry> |
|
115 </row> |
|
116 </tbody> |
|
117 </tgroup> |
|
118 </table><p>If the IIC controller is not to be used, then the client |
|
119 interface API classes are:</p><table id="GUID-2A6EAA19-F725-447C-8041-F60B5EFA32C5"> |
|
120 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
121 <thead> |
|
122 <row> |
|
123 <entry valign="top"><p><b>Name</b></p></entry> |
|
124 <entry valign="top"><p><b>Description</b></p></entry> |
|
125 </row> |
|
126 </thead> |
|
127 <tbody> |
|
128 <row> |
|
129 <entry><p><xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref></p></entry> |
|
130 <entry><p>Client interface API for the master channel operation.</p></entry> |
|
131 </row> |
|
132 <row> |
|
133 <entry><p><xref href="GUID-22FF70C1-A805-3EBB-B142-15FD16D00837.dita"><apiname>DIicBusChannelSlave</apiname></xref></p></entry> |
|
134 <entry><p>Client interface API for the slave channel operation.</p></entry> |
|
135 </row> |
|
136 <row> |
|
137 <entry><p><xref href="GUID-26DBC836-03F1-31C4-BBFF-1F406E2BAEDB.dita"><apiname>DIicBusChannelMasterSlave</apiname></xref></p></entry> |
|
138 <entry><p>Client interface API for the master slave channel operation.</p></entry> |
|
139 </row> |
|
140 </tbody> |
|
141 </tgroup> |
|
142 </table></section> |
|
143 </conbody></concept> |