--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84.dita	Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-0C8318B1-71D7-5384-97EB-85CBBC3E6B84" xml:lang="en"><title>IIC SHAI Implementation Layer: Master Channel</title><shortdesc>This document explains how to implement the a master channel
+in the SHAI implementation layer of IIC. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-38D02829-2B52-4E2E-ABD0-D88D5F1B5FBC"><title>Purpose</title> <p>This document explains how to implement a master channel on the
+SHAI implementation layer of IIC. </p> <p><b>Intended Audience</b> </p> <p>Base porting engineers. </p> <p><b>Introduction</b> </p> <p>IIC buses (a term used in this document to represent serial inter-chip
+buses that IIC can operate on) are a class of bus used to transmit
+non time-critical data between components of a hardware system. </p> </section>
+<section id="GUID-69ED3F3A-8D85-4940-B9C7-691081EC5E93"><title>Implementing
+a master channel</title> <p>You should read and understand the template
+port at<filepath> \os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic\iic_master</filepath> as this will provide most of the information you need to implement
+the master channel.</p><p>To implement the SHAI implementation layer
+of an IIC channel as master you must write a class extending <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. You must implement certain pure virtual
+functions of the parent class in the subclass. Those functions and
+any other functions which you write in the subclass are called the
+SHAI implementation layer. The functions inherited from the parent
+class are called the Platform Independent Layer (PIL). </p> <p>The
+four functions you must implement are: </p> <ul>
+<li id="GUID-B49F1DAB-AB30-5C95-BFAF-93D8DC779371"><p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref>  </p> </li>
+<li id="GUID-A402D653-D8D5-5031-A647-ED02B95B4857"><p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref>  </p> </li>
+<li id="GUID-AF3B74BE-9193-51CD-B7E4-E721F2CCDC98"><p> <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref>  </p> </li>
+<li id="GUID-242CB2B6-0DB0-53A0-B951-1FACA037DEE0"><p> <xref href="GUID-A5E66E7E-E03B-3249-A5E5-F0E5DFC3B3EB.dita"><apiname>CheckHdr()</apiname></xref>  </p> </li>
+</ul> <p>You must also provide the following functionality: </p> <ul>
+<li id="GUID-7C3DDA6A-1976-518C-90D8-27BD1D2B9C23"><p>validation of
+input, </p> </li>
+<li id="GUID-6E61EE3F-D8A1-58B4-A129-61A42E710150"><p>interrupt service
+routines, and </p> </li>
+<li id="GUID-8018060E-C5D6-5C9C-BA63-05B9DAE47823"><p>reporting on
+transmission status using the callback function <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref> with the relevant error code. </p> </li>
+</ul> <p>Your implementation of the SHAI implementation layer will
+need to call functions of the PIL. You are restricted to using a certain
+subset of these. </p> <p><b>Implementing DoCreate()</b> </p> <p> <xref href="GUID-11C2715E-409F-3F24-AE8F-89CF5A893B80.dita"><apiname>DoCreate()</apiname></xref> is the second phase constructor of your class.
+Implement it to perform functionality including: </p> <ul>
+<li id="GUID-47401DEC-3072-541A-BE75-034E1ABFE40A"><p>call the PIL
+function <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>, </p> </li>
+<li id="GUID-C41E4C4B-10CE-5393-9326-83110FEBB244"><p>create the DFC
+queue for the driver and assign it to the driver by calling <xref href="GUID-391B9E13-9A66-3DD4-872F-439C46022448.dita"><apiname>SetDfcQueue()</apiname></xref>, </p> </li>
+<li id="GUID-D2E8E3FB-EF15-5257-BDD8-BA72D80EA129"><p>initialize the
+hardware, setting up interrupts, and </p> </li>
+<li id="GUID-851D395C-330B-5492-AD1A-A54A484ED63D"><p>initialize the
+other data structures representing the channel. </p> </li>
+</ul> <p><b>Implementing DoRequest()</b> </p> <p> <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> is the gateway function to the SHAI implementation layer. It configures
+the interface using the supplied configuration and processes transactions.
+It takes one argument <xref href="GUID-2803075B-3B59-3DF1-BB22-A6DF4DB6AA58.dita"><apiname>aTransaction</apiname></xref>, a pointer to
+a <xref href="GUID-1A326AA6-7C9F-3E61-9B55-34FCE771EB96.dita"><apiname>TIicBusTransaction</apiname></xref> object created by the client:
+you use the protected data functions of the PIL (listed below) to
+extract the data needed to perform the associated transfers. Implement <xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname>DoRequest()</apiname></xref> with functionality including the following: </p> <ul>
+<li id="GUID-A7E758C2-89C0-5CCE-A5D2-1F7019CDF890"><p>Extract the
+transaction parameters, that is the transaction header and transfers
+(<xref href="GUID-73FDF24F-0B9D-3A97-B9BB-E021257E77F1.dita"><apiname>TIicBusTransfer</apiname></xref>), </p> </li>
+<li id="GUID-EF3B0B5A-E03B-58FF-8E8B-90EB6C7F5CFF"><p>configure the
+interface with the configuration supplied in the transaction header, </p> </li>
+<li id="GUID-A38796B7-A3F3-50D0-86DC-CCB4D3C69658"><p>set up the hardware
+to start the first transfer, that is </p> <ul>
+<li id="GUID-94CAE80B-2221-5664-85FB-B06666851DDB"><p>extract the
+first transfer for one direction by calling <xref href="GUID-2ADBFCF5-109F-33BA-97D1-44DA7D8604F2.dita"><apiname>GetTransHalfDuplexTransfer()</apiname></xref>, </p> </li>
+<li id="GUID-4613E372-DA10-5105-816F-1890A4314CDD"><p>and if the transfer
+is full duplex extract the first transfer for the second direction
+by calling <xref href="GUID-0C7ACFD8-279D-385D-8BF4-B870ABD185CE.dita"><apiname>GetTransFullDuplexTransferPtr()</apiname></xref>, </p> </li>
+</ul> <p>in each case filling hardware FIFO buffers, enabling interrupts
+and so on, </p> </li>
+<li id="GUID-B3CF4DEE-DAA2-5ADD-BA08-9861C457AF35"><p>call the PIL
+function <xref href="GUID-967E4167-498F-3714-8CFB-8273968C551B.dita"><apiname>StartSlaveTimeoutTimer()</apiname></xref>, </p> </li>
+<li id="GUID-48D2A463-EB97-5604-8106-9980AAE0FFE6"><p>instruct the
+hardware to start transmission, and </p> </li>
+<li id="GUID-45785C69-E8FB-5548-B8FF-3EA3EE45447F"><p>return either
+an error code or <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> </li>
+</ul> <p>The effect of calling <codeph>DoRequest()</codeph> should
+be to start the sequence of transfers comprising the transaction.
+Typically, at the end of each transfer a hardware interrupt and associated
+DFC callback occurs. If the PIL function <codeph>StartSlaveTimeout()</codeph> was called to monitor the duration of an individual transfer, the
+PIL function <codeph>CancelTimeout()</codeph> should be called to
+cancel the timer. If the transfer was successful and a call to get
+the next transfers succeeds, the next transfer is set up. This continues
+until either all the transfers have been processed, or there is an
+error; after that, the PIL method <codeph>DIicBusChannelMaster::CompleteRequest()</codeph> is called to indicate the result.  </p> <p><b>Implementing HandleSlaveTimeout()</b> </p> <p>If the timer started by the PIL method <codeph>StartSlaveTimeoutTimer()</codeph> expires then the slave peripheral has not responded within the expected
+time, and in such case some SHAI implementation layer-specific recovery
+will be required; this is to be provided by the implementation of
+ <codeph>HandleSlaveTimeout()</codeph>. Implement it with functionality
+including: </p> <ul>
+<li id="GUID-37E4C87F-4980-5651-BD13-2AD8622A8F52"><p>stop the transmission, </p> </li>
+<li id="GUID-667655D7-76B0-5F0A-BFA5-F74B964AF982"><p>disable the
+hardware, and </p> </li>
+<li id="GUID-DCF7198C-BFB2-58EF-9014-C9BEB31F57E4"><p>call the PIL
+function <codeph>CompleteRequest()</codeph> with the <xref href="GUID-BAC2386E-8168-3CDB-9F9F-180319EF6920.dita"><apiname>KErrTimedOut</apiname></xref> error code. </p> </li>
+</ul> <p><b>Implementing CheckHdr()</b> </p> <p>Implement <xref href="GUID-B44147A7-D880-3510-A3F1-D73E9B5F8230.dita"><apiname>CheckHdr().</apiname></xref> This is the function which is called in the
+context of the client thread when the client calls <xref href="GUID-D0F8DF19-790F-3FE5-89E4-057C240AD3FE.dita"><apiname>QueueTransaction()</apiname></xref>. Implement it with the following functionality: </p> <ul>
+<li id="GUID-42548EF0-4A41-5095-8541-CDC8BF6032D4"><p>check if the
+header of the transaction is valid. </p> </li>
+</ul> <p><b>Using the Platform Independent Layer</b> </p> <p>You can
+only use certain functions of the PIL. Most are used to access private
+data of the parent class. Others provide functionality which is generic
+to IIC buses. These are: </p> <ul>
+<li id="GUID-1034BC57-BC77-5D7F-9385-3ACCC0EFF6DE"><p> <xref href="GUID-995FA70D-F28C-3AA6-BB6A-528210F3716E.dita"><apiname>DIicBusChannelMaster()</apiname></xref>, the constructor of the superclass <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref> with arguments representing the bus type and the duplex settings. </p> </li>
+<li id="GUID-27AE6A8A-3C0E-5DC3-917B-0F23D3D6E7C2"><p> <xref href="GUID-741A0FD7-5A5A-31B0-BB5F-763B5795009C.dita"><apiname>Init()</apiname></xref>. Initializes <xref href="GUID-FA3881ED-B736-34EB-8F1F-026BE1602B1B.dita"><apiname>DIicBusChannelMaster</apiname></xref>. </p> </li>
+<li><p>•<codeph>SetDfcQ()</codeph>. Sets the driver's DFC queue to
+be used by DFCs in the PIL. </p></li>
+<li id="GUID-B90804B6-0A44-5764-B6AD-62F0A0E0C8C5"><p> <xref href="GUID-30953225-638A-3627-8183-544E127FE72C.dita"><apiname>StartSlaveTimeOutTimer()</apiname></xref>. Starts a timer which causes the <xref href="GUID-AD480427-A00E-3BB3-AD62-1B91A86B37A2.dita"><apiname>HandleSlaveTimeout()</apiname></xref> callback to run if the transaction (or transfer, SHAI implementation
+layer decides) is not completed in the specified time. </p> </li>
+<li id="GUID-4AC4BD6D-2123-5151-B744-8785A4D4E364"><p> <xref href="GUID-03DA2EEC-8E8C-30FC-9956-E721184FE43E.dita"><apiname>CancelTimeOut();</apiname></xref>. Cancels the timeout timer which monitors the transaction time. </p> </li>
+<li id="GUID-B61C0B7E-43EF-55E6-9BA6-9791F3858D76"><p> <xref href="GUID-853C87F1-0E44-3B1E-A97E-6461F1188B3A.dita"><apiname>CompleteRequest()</apiname></xref>. Called to signal the PIL about completed transactions, transmission
+errors and timeouts. </p> </li>
+</ul> <p>The functions accessing private members of <xref href="GUID-1A326AA6-7C9F-3E61-9B55-34FCE771EB96.dita"><apiname>TIicBusTransaction</apiname></xref> are: </p> <table id="GUID-11F852E6-4180-5F2D-BC57-5F45946C9F71">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Function</entry>
+<entry>Returns</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <codeph>GetTransactionHeader() </codeph> </p> </entry>
+<entry><p>A pointer to the configuration header. </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>GetTransHalfDuplexTfrPtr()</codeph>  </p> </entry>
+<entry><p>A pointer to the head of the list of half duplex transfers. </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>GetTransFullDuplexTfrPtr()</codeph>  </p> </entry>
+<entry><p>A pointer to the head of the list of full duplex transfers. </p> </entry>
+</row>
+<row>
+<entry><p><codeph>GetTransCallback()</codeph></p></entry>
+<entry><p>A pointer to the callback function</p></entry>
+</row>
+<row>
+<entry><p><codeph>GetTransFlags()</codeph></p></entry>
+<entry><p>a pointer to the transaction flags</p></entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The functions accessing private members of <xref href="GUID-73FDF24F-0B9D-3A97-B9BB-E021257E77F1.dita"><apiname>TIicBusTransfer</apiname></xref> are: </p> <table id="GUID-6B66FB92-634F-5B57-8AEE-7D90606BF26F">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Function</entry>
+<entry>Returns</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-779C14B5-7D9D-3582-BE22-21CB668FADE6.dita"><apiname>GetTferType()</apiname></xref>  </p> </entry>
+<entry><p>The transfer type, EMasterRead or <xref href="GUID-5E76AC81-4074-337D-86E4-B3FC14062B51.dita"><apiname>EMasterWrite</apiname></xref>, defined in the enumeration <xref href="GUID-5FBF20DE-E998-3281-A85E-EF56A1FDDFA3.dita"><apiname>TReqType</apiname></xref>. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-D55D721A-4F5C-3B94-9351-971269E94493.dita"><apiname>GetTferBufGranularity()</apiname></xref>  </p> </entry>
+<entry><p>The size of the buffer item in bits, typically 8 or 16. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-8A2E8454-957C-3F24-AF23-CF375C30EB05.dita"><apiname>GetTferBuffer()</apiname></xref>  </p> </entry>
+<entry><p>A pointer to the buffer where the data is stored. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-FD0F5059-1B2B-3477-907C-9BC50D6CF6AE.dita"><apiname>GetTferNextTfer()</apiname></xref>  </p> </entry>
+<entry><p>A pointer to the next transfer in the transaction. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table><note>In addition to the above functions, there are additional
+functions for accessing transactions with preambles, extending transactions
+(multitransactions) and extended transactions with preamble. Refer
+to the header file for details on these functions.</note> </section>
+</conbody><related-links>
+<link href="GUID-052F58B7-117B-5EDD-A3D5-CB0DE6A4E239.dita"><linktext>IIC
+SHAI Implementation Layer:  Generic Considerations</linktext></link>
+<link href="GUID-C9644081-004E-5DA0-8133-A32EEA91EF5E.dita"><linktext>IIC
+SHAI implementation Layer: Slave Channel</linktext></link>
+<link href="GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita"><linktext>Client
+of Master Channel Tutorial</linktext></link>
+<link href="GUID-F461CBB3-F8D1-5961-AD51-5741143A1CB1.dita"><linktext>Client
+of Slave Channel Tutorial</linktext></link>
+<link href="GUID-B2F86F54-EF50-56DB-ADF7-15325AC9324D.dita"><linktext>IIC
+Concepts</linktext></link>
+<link href="GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita"><linktext>I2C
+Technology Guide</linktext></link>
+</related-links></concept>
\ No newline at end of file