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-B6F0C909-6E58-584E-9270-8066337FCE0F" xml:lang="en"><title>Client

    13 Tutorial</title><shortdesc>Explains how to use the MMC Controller interfaces to use MMC hardware.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-388CEB1C-BA81-593F-81D3-C0BD72A405E0"><title>Client interfaces</title> <p>The

    15 following diagram shows the relationship between the Controller and its clients,

    16 and also shows aspects of the relationship between the constituent parts.

    17 In this case, the client is the MultiMediaCard driver, although in general

    18 this could be some other device driver. </p><fig id="GUID-FF02FE34-4E77-42DE-89BC-4D789E6A310D">

    19 <image href="GUID-6597A895-37D5-51D1-86B3-E74F6E845899_d0e23392_href.png" placement="inline"/>

    20 </fig> <p>The session is used to pass commands either to the entire stack,

    21 i.e. a broadcast command, or to individual cards in the stack. </p> <p>The

    22 session provides access to the stack of cards, via a pointer to a stack object,

    23 the <codeph>iStackP</codeph> private member. The session is used to pass commands

    24 either to the entire stack, i.e. a broadcast command, or to individual cards

    25 in the stack. An individual card can be accessed via a pointer to the card

    26 object, the <codeph>iCardP</codeph> private member. The card objects, <xref href="GUID-913FA896-4237-3E47-996F-547E325550AD.dita"><apiname>TMMCCard</apiname></xref> types,

    27 are data members of the card array object, <xref href="GUID-A460F779-52AB-3ED0-AF13-41B9BC5B2A71.dita"><apiname>TMMCardArray</apiname></xref>,

    28 which, in turn is a data member of the stack object. </p> </section>

    29 <section id="GUID-A0B4E830-24DD-5C9C-A76B-CD1DE372A9FE"><title>Using the MultiMediaCard

    30 stack</title> <p>Clients of the MMC Controller such as the MMC Media Driver

    31 uses the MMC Controller as follows: </p> <ul>

    32 <li id="GUID-F4C2C756-5793-59BE-9DAB-E7960B4E5F8D"><p>requests a pointer to

    33 the stack object, through which the client can obtain pointers to the individual

    34 card objects and interrogate the cards, finding out their media type, capacity,

    35 and capability (via the card’s <xref href="GUID-C6858312-FC9A-34C9-B442-557F7558B5C4.dita"><apiname>TCSD</apiname></xref> object), and whether

    36 the card is present or ready. </p> </li>

    37 <li id="GUID-592769F9-B9B0-583E-A76C-DF8EB0A5A4B2"><p>creates a session object,

    38 an instance of the <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita"><apiname>DMMCSession</apiname></xref> class, providing a callback

    39 function for its constructor. The callback is encapsulated as a <xref href="GUID-F59F1805-95FB-3BDD-97A5-4FD6048DE2E8.dita"><apiname>TMMCCallBack</apiname></xref> object. </p> </li>

    40 <li id="GUID-66E909B9-8B32-5036-BCAA-486A7F047BBD"><p>initiates the session

    41 with the pointer to the stack object: <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-72859BCF-4979-37F3-BF32-45181F64755F"><apiname>DMMCSession::SetStack()</apiname></xref> . </p> </li>

    42 </ul> <p>The client interacts with the stack in the following manner: </p> <ol id="GUID-AE800793-AEF9-5F11-9CF2-A6FEB6827265">

    43 <li id="GUID-2957F643-771C-5279-821F-875843F42CAC"><p>it sets the session

    44 up with the pointer to the card object, by calling <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-60FAAA31-A5E1-3DCF-93AE-459BCC8C9730"><apiname>DMMCSession::SetCard()</apiname></xref>. </p> </li>

    45 <li id="GUID-4B117791-3B0D-552F-81AC-85D0905EEB91"><p>it sets the session

    46 up to do a specific job, such as a MultiMediaCard macro command, or a lower

    47 level card command, using the API provided by <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita"><apiname>DMMCSession</apiname></xref>. </p> </li>

    48 <li id="GUID-0F43C846-6E62-5539-99E1-1DBCF4E911CE"><p>it presents the session

    49 to the stack for execution, by calling <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-8DA6B49E-FED0-3E83-8D2F-EA7B61C28015"><apiname>DMMCSession::Engage()</apiname></xref>. </p> </li>

    50 <li id="GUID-BF673228-633B-5E99-9396-0CE6ABE3360E"><p>On completion, the stack

    51 calls the client’s callback function. The client then can repeat the cycle

    52 from step 1 or 2. </p> </li>

    53 </ol> <p>The client can override the default bus configuration settings, i.e.

    54 change the bus clock, enable retries, change time-out values, restore defaults

    55 etc., using the session's stack configuration object, <xref href="GUID-89631250-7D11-3E89-9785-7DF779B2AB38.dita"><apiname>TMmCStackConfig</apiname></xref>,

    56 although in practice, there is rarely a need to do this. </p> </section>

    57 <section id="GUID-6638C350-37FE-5CF7-AF0B-0EF763936DF3"><title>Locking the

    58 MultiMediaCard stack</title> <p>The <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita"><apiname>DMMCSession</apiname></xref> API includes

    59 general lower level functions to issue any single command or series of commands

    60 including those currently unknown to the controller. This allows application

    61 specific commands to be supported. It also allows the controller to support

    62 new commands introduced in later versions of the specification (e.g. commands

    63 to support I/O cards). </p> <p>When issuing a series of application specific

    64 commands, the client will want to lock the stack, preventing any other client

    65 from generating bus activity during this period. This is accomplished by calling <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-BA7DE143-BDE0-31DB-8C85-1073F0D6175C"><apiname>DMMCSession::SetupCIMLockStack()</apiname></xref> and

    66 then engaging that session. If successful, the stack will be locked until <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-5F153F42-9527-3561-AB05-B36DD28201A1"><apiname>DMMCSession::UnlockStack()</apiname></xref> is

    67 called. </p> <p>As it may take time for the controller to lock the stack for

    68 that session, the mechanism for locking the stack involves submitting a session

    69 even though no bus activity results. If this session completes successfully

    70 then the stack is locked. The client can then go ahead and invoke its series

    71 of commands - configuring that same session object as necessary each time

    72 and submitting it. </p> </section>

    73 <section id="GUID-4B239C05-3CCF-4FB5-BD11-DA7DFF52DA95"><title>See also</title> <p> <xref href="GUID-9573F7B9-76E9-5DCB-A498-C0DE59606911.dita">Concepts</xref> </p> </section>

    74 </conbody></concept>