|
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-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239" xml:lang="en"><title>IIC SHAI Implementation Layer: Generic Considerations</title><shortdesc>This document explains how to implement the SHAI implementation |
|
13 layer for IIC.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-C3EE341A-BEAB-4E0C-A91E-7A1A285BCE96"><title>Purpose</title> <p>This document covers information which is generic to master and |
|
15 slave channel implementation </p> <p><b>Intended Audience</b> </p> <p>Base porting engineers. </p> <p><b>Introduction</b> </p> <p>IIC |
|
16 buses (a term used in this document to represent serial inter-chip |
|
17 buses that IIC can operate on) are a class of bus used to transmit |
|
18 non time-critical data between components of a hardware system. </p> </section> |
|
19 <section id="GUID-38B543E8-06DB-417F-8B8E-84F6B43DF8BF"><title>Generic |
|
20 architecture</title> <p>Different IIC buses have a large amount of |
|
21 functionality in common, but some functionality is specific to individual |
|
22 implementations. For this reason, the IIC software has an architecture |
|
23 consisting of two layers, the Platform Independent Layer (PIL) and |
|
24 the SHAI implementation layer. The Platform Independent Layer is a |
|
25 set of classes which encapsulate generic functionality and have been |
|
26 implemented for you. The SHAI implementation layer is an interface |
|
27 which you must implement yourself to encapsulate the functionality |
|
28 specific to the platform you are working on. </p> <p>You implement |
|
29 the SHAI implementation layer by subclassing the classes of the Platform |
|
30 Independent Layer and writing functions that provide an abstraction |
|
31 of your hardware. To access the hardware you are strongly recommended |
|
32 to use existing Symbian APIs such as e.g. <codeph>AsspRegister</codeph> to access hardware registers, or <codeph>GPIO</codeph> to access |
|
33 GPIO pins). </p> <p>An IIC channel operates in one of two modes, master |
|
34 and slave, and there are separate master and slave APIs to be implemented. |
|
35 In master mode, a channel and a client communicating with that channel |
|
36 execute in two separate threads. In slave mode there is only one thread |
|
37 for both channel and client. </p> <p>The SHAI implementation and platform |
|
38 independent APIs assume an interrupt-driven approach to implementation. |
|
39 An event on hardware triggers an interrupt, which then signals this |
|
40 event to the channel thread (where client is master) or client thread |
|
41 (where client is slave). This means that implementation involves writing |
|
42 interrupt service routines (ISRs) and a DFC queue to hold the callbacks |
|
43 which respond to them. For both master and slave operation, the callbacks |
|
44 are queued for execution on the client thread - so the client thread |
|
45 must not be blocked, otherwise the callbacks will never run.</p><p>Clients of a master channel request transactions for execution in |
|
46 either a synchronous or asynchronous manner. This results in the transaction |
|
47 being entered in the channel’s request queue. </p><p>If synchronous |
|
48 execution is requested, the client thread is blocked until the transaction |
|
49 completes (either an ISR or polling mechanism in the SHAI implementation |
|
50 layer recognizes the transaction has completed, and it calls the PIL |
|
51 method <codeph>CompleteRequest()</codeph>, which will unblock the |
|
52 client thread. </p><p>If asynchronous execution is requested, the |
|
53 client thread is not blocked, and may continue to perform other tasks. |
|
54 In the meanwhile, the channel thread will retrieve the next transaction |
|
55 from the request queue and pass it to the SHAI implementation layer |
|
56 for processing. When the transaction completes, the SHAI implementation |
|
57 layer calls the PIL method <codeph>CompleteRequest()</codeph> and |
|
58 this adds the client’s callback to the client’s DFC queue. </p><p>A client of a slave channel provides receive and transmit buffers |
|
59 to be used and specifies the types of event (trigger) that it wishes |
|
60 to be notified of. When ANY event occurs, the SHAI implementation |
|
61 layer should call the PIL method <codeph>NotifyClient()</codeph>; |
|
62 this determines whether the reported triggers qualify for notifying |
|
63 the client – if so, the client callback is added to the client’s DFC |
|
64 queue for execution. Note that the same mechanism is used to notify |
|
65 the client of completion of asynchronous capture of the channel, and |
|
66 of bus errors.</p> <p>You should refer to the template port at <filepath>\os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic</filepath> for more information. </p> </section> |
|
67 </conbody><related-links> |
|
68 <link href="GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84.dita"><linktext>IIC |
|
69 SHAI Implementation Layer: Master Channel</linktext></link> |
|
70 <link href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita"><linktext>IIC |
|
71 SHAI Implementation Layer: Slave Channel</linktext></link> |
|
72 <link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client |
|
73 of Master Channel Tutorial</linktext></link> |
|
74 <link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client |
|
75 of Slave Channel Tutorial</linktext></link> |
|
76 <link href="GUID-B2F86F54-EF50-56DB-ADF7-15325AC9324D.dita"><linktext>IIC |
|
77 Concepts</linktext></link> |
|
78 <link href="GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita"><linktext>I2C |
|
79 Technology Guide</linktext></link> |
|
80 </related-links></concept> |