|
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-C24A5B52-0B40-53B2-BF85-6ECC35BDCBA5" xml:lang="en"><title>IIC Implementation Guide</title><shortdesc>Describes how to implement the IIC platform service.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
13 <p>This document describes the overview of how to implement the IIC |
|
14 platform service APIs and directs you to more specific documentation. </p> |
|
15 <section id="GUID-16DD5496-C5F7-43C3-9C90-119E32AD50FE"><title>Purpose</title> <p>The IIC platform service APIs provides a means of accessing devices |
|
16 that are connected onto a multi-wire bus within the phone. These platform |
|
17 service APIs rely on hardware-specific implementation in the SHAI |
|
18 implementation layer of the IIC implementation. This hardware-specific |
|
19 implementation is primarily creating concrete hardware-specific implementations |
|
20 of functions defined in the Platform Independent Layer (PIL),.</p> <p><b>Intended Audience:</b> </p> <p>This document is intended for |
|
21 hardware device implementers who want to write adaptation software |
|
22 to use their specific serial bus hardware with IIC. </p> </section> |
|
23 <section id="GUID-A0142A52-534D-4C0D-8145-85C0A84DDBB5"><title>Background</title><p>There are two main forms of IIC operation: </p><ul> |
|
24 <li><p>Master operation</p></li> |
|
25 <li><p>Slave mode </p></li> |
|
26 </ul><p>A master node on a bus controls transactions and is responsible |
|
27 for sending commands along the bus to select the slave node which |
|
28 is to send or receive the commands and data. A slave node receives |
|
29 instructions from a master node and sends or receives commands and |
|
30 data. The OS device drivers may act as a slave or a master node, or |
|
31 in some bus technologies, the role of master and slave can be exchanged.</p><p>IIC has channels, which represent a connection between two nodes |
|
32 on the bus. The channel has a queue for commands and will process |
|
33 each command in turn. </p><p>A device driver can either use the IIC |
|
34 Controller to access channels, or if there is a dedicated node that |
|
35 is going to be used by a particular device driver, then the device |
|
36 driver can talk directly to that node through IIC without using the |
|
37 IIC Controller.</p> </section> |
|
38 <section id="GUID-5CF49F33-E7B8-4FE6-AB97-A6B5EB38F9FF"><title>The |
|
39 IIC platform service API</title> <p>The <codeph>IicBus</codeph> class |
|
40 provides the platform service API for device drivers that want to |
|
41 use the IIC Controller. For Controller-less operation, the platform |
|
42 service API is formed by the <codeph>DIicBusChannelMaster</codeph>, <codeph>DIicBusChannelSlave</codeph> and <codeph>DIicBusChannelMasterSlave</codeph> classes.</p> <p>A summary of methods in the <codeph>IicBus</codeph> class are : </p> <table id="GUID-C77D090D-F2CA-500A-9E75-EDF80CB60CA5"> |
|
43 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
44 <tbody> |
|
45 <row> |
|
46 <entry><p> <b>Method</b> </p> </entry> |
|
47 <entry><p> <b>Purpose</b> </p> </entry> |
|
48 </row> |
|
49 <row> |
|
50 <entry><p>QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction) </p> </entry> |
|
51 <entry><p>Queues a transaction for synchronous completion. </p> </entry> |
|
52 </row> |
|
53 <row> |
|
54 <entry><p>QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, |
|
55 TIicBusCallback* aCallback) </p> </entry> |
|
56 <entry><p>Queues a transaction for asynchronous completion. </p> </entry> |
|
57 </row> |
|
58 <row> |
|
59 <entry><p>CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction) </p> </entry> |
|
60 <entry><p>Cancels a previously queued transaction (if the transaction |
|
61 was queued asynchronously). </p> </entry> |
|
62 </row> |
|
63 <row> |
|
64 <entry><p>CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* |
|
65 aCallback, TInt& aChannelId, TBool aAsynch=EFalse) </p> </entry> |
|
66 <entry><p>Capture a slave channel. </p> <p>The aAsynch parameter indicates |
|
67 if this is to be done synchronously or asynchronously. The default |
|
68 is synchronous. </p> </entry> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p>ReleaseChannel(TInt aChannelId) </p> </entry> |
|
72 <entry><p>Release a previously captured Slave channel. </p> </entry> |
|
73 </row> |
|
74 <row> |
|
75 <entry><p>RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 |
|
76 aBufGranularity, TInt8 aNumWords, TInt8 aOffset) </p> </entry> |
|
77 <entry><p>Register a receive buffer with this slave channel. </p> </entry> |
|
78 </row> |
|
79 <row> |
|
80 <entry><p>RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 |
|
81 aBufGranularity, TInt8 aNumWords, TInt8 aOffset) </p> </entry> |
|
82 <entry><p>Register a transmit buffer with this slave channel. </p> </entry> |
|
83 </row> |
|
84 <row> |
|
85 <entry><p>SetNotificationTrigger(TInt aChannelId, TInt aTrigger) </p> </entry> |
|
86 <entry><p>For a transmit operation, this sets the notification trigger, |
|
87 sets the receive path and starts a transmit operation (if the node |
|
88 is being addressed). For a receive operation, this sets the notification |
|
89 trigger. </p> </entry> |
|
90 </row> |
|
91 <row> |
|
92 <entry><p>StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, |
|
93 TAny* aParam2) </p> </entry> |
|
94 <entry><p>Interface to provide extended functionality. </p> </entry> |
|
95 </row> |
|
96 </tbody> |
|
97 </tgroup> |
|
98 </table> <p>The platform service APIs for controller-less operation |
|
99 are almost exactly the same, but with the addition of channel constructors |
|
100 and destructors.<note> Please refer to <filepath>iic.h</filepath>, <filepath>iic_channel.cpp</filepath>and <filepath>iic_channel.h</filepath> for |
|
101 more details on these APIs. </note> </p> </section> |
|
102 <section id="GUID-7A8667A0-6061-446C-AE93-6BD3E0DB4952"><title>Implementation |
|
103 details</title><p>You must next read:<ul> |
|
104 <li><p><xref href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita">IIC |
|
105 SHAI Implementation Layer: Generic Considerations</xref></p></li> |
|
106 <li><p><xref href="GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84.dita">IIC |
|
107 SHAI Implementation Layer: Master Channel</xref></p></li> |
|
108 <li><p><xref href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita">IIC |
|
109 SHAI Implementation Layer: Slave Channel</xref></p></li> |
|
110 </ul></p><p/></section> |
|
111 </conbody><related-links> |
|
112 <link href="GUID-C661BFA4-6C39-476A-8DE0-08E18AA0F548.dita"><linktext>IIC |
|
113 Overview</linktext></link> |
|
114 <link href="GUID-CB0FC4F4-6DAB-4ADD-B044-0E8B9365B4D5.dita"><linktext>IIC |
|
115 Concepts Overview</linktext></link> |
|
116 </related-links></concept> |