<?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-BE6AFD38-5952-537F-848C-C76C8F5FA9BF" xml:lang="en"><title>MMC
Controller Architecture</title><shortdesc>Describes the library and class architecture of the MMC Controller.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-50AB2022-B205-525B-83F9-0DE0275EC3EF"><title>Library architecture</title> <p>Symbian
platform provides support for MultiMediaCards through the MultiMediaCard controller.
The controller manages access to the MultiMediaCard hardware on behalf of
media drivers or any other device driver. </p> <p>The controller is implemented
as a specialisation of the Symbian OS peripheral bus controller abstraction.
There are two DLLs that make up the Controller: </p> <ul>
<li id="GUID-9FAE6679-B1FC-52FA-9276-C406426992C2"><p>a generic DLL, provided
by Symbian platform; this is called <filepath>epbusm.dll</filepath>. This
is also referred to as the <i>platform independent layer</i>. </p> </li>
<li id="GUID-42C30CFD-2EF1-5B98-9939-09879301E936"><p>a variant DLL, containing
the code that is specific to the hardware; this is usually called <filepath>epbusmv.dll</filepath>.
This is also referred to as the <i>platform specific layer</i>. </p> </li>
</ul> <p>The generic DLL is itself split into two layers: </p> <ul>
<li id="GUID-9184766A-7CE3-5080-B535-0AD27EC7BF48"><p>a generic peripheral
bus layer that implements behaviour that is common to dealing with all types
of peripheral bus </p> </li>
<li id="GUID-FB7150C8-A253-5531-A6CA-8658684482A5"><p>a generic MMC layer
that implements the more specialized behaviour required for dealing with MultiMediaCards. </p> </li>
</ul> <fig id="GUID-6F516C8A-9114-50A1-A714-8BA9DD081C08">
<image href="GUID-18E72D18-F355-5D3A-9469-E4917BFC3058_d0e383204_href.png" placement="inline"/>
</fig> <p>Both DLLs are implemented as kernel extensions, which means that
they are loaded very early during system initialisation. </p> <p>The controller
can be thought of as a server managing access to the MultiMediaCard hardware
with its clients being the local media device driver and other device drivers.
The following diagram gives you a simplified picture of data/control flow
as a result of a file access from the user side. </p> <fig id="GUID-D84379AB-36E2-5679-B154-40FDDF6FE334">
<image href="GUID-BA217AA7-F21F-5586-8304-FE821E06C86E_d0e383215_href.png" placement="inline"/>
</fig> <p>The MultiMediaCard media driver defines and implements the standard
media driver interface derived from <xref href="GUID-A0D4EB25-0BA4-39EE-874B-465EB9628DCC.dita"><apiname>DMediaDriver</apiname></xref>. This
is the client of the MultiMediaCard controller. </p> <fig id="GUID-17F345F3-B579-5D78-BE22-0CA50A88FAAE">
<image href="GUID-DF3045C7-4BDA-53AF-85E4-A8AAD99F40F7_d0e383227_href.png" placement="inline"/>
</fig> <p>Requests to the controller can also come from other device drivers.
This means that the architectural picture can be extended as shown below: </p> <fig id="GUID-53AF7993-0A93-5728-9609-0133E66AED78">
<image href="GUID-5686E787-537F-5B32-B719-34EF5B7F0D37_d0e383235_href.png" placement="inline"/>
</fig> <p>The controller currently supports a single stack capable of holding
up to 4 cards. In a future development, it may become capable of supporting
more than 1 stack. Note however, that Symbian platform allows more than one
peripheral bus controller. </p> <p>The controller can handle multiple requests
outstanding simultaneously, i.e. multiple drivers each with a session engaged
(a session is a unit of work for the MMC stack). Internally, it schedules
these requests onto the bus, automatically putting the appropriate card into
the transfer state etc. </p> <p>A platform containing a card socket is expected
to provide a means of detecting when a card is inserted or removed from the
stack (e.g. a media door interrupt). The controller does not attempt to initialise
and identify newly inserted cards immediately. Instead, cards remain unidentified
until they are interrogated by a client. </p> <p>For hardware interfaces that
allow multiple cards in a single stack, the MultiMediaCard system supplies
no means of identifying a particular socket position within the stack. As
cards are inserted and removed, the potential exists for those cards which
remain to be allocated different card numbers (and ultimately a different
drive letter than that allocated previously) once the stack is re-initialised.
To avoid this, the controller maintains a fixed card number for a given card
for as long as it remains in the Symbian platform device (by storing the CID
of each card present). This means that a card will have a constant drive letter
for as long it remains in the Symbian platform device. However, if a card
is removed, and then subsequently re-inserted into exactly the same slot in
the stack, then there is no guarantee that it will be allocated the same card
number, and therefore, no guarantee that it will have the same drive letter
as before. </p> </section>
<section id="GUID-92F5EBE4-C9AD-5D9A-A80E-9AFD1A09B6B3"><title>Class architecture</title> <p>The
following diagram gives a more detailed view of the MultiMediaCard controller
in terms of the socket, stack, session, power supply and media change objects. </p> <fig id="GUID-8C814B4E-268A-5007-8D70-DEDF32F4B401">
<image href="GUID-431A08D4-46DD-5A9D-B2A4-3D58C9B1E9E7_d0e383260_href.png" placement="inline"/>
</fig> <p id="GUID-BA12AC03-4A9C-5B1A-BC06-D171BCAB9DB2"><b>The socket</b> </p> <p>The
Symbian platform implementation of MultiMediaCard uses the idea of a socket.
A socket corresponds to a physical device on a given peripheral bus. </p> <p>In
general, a socket is associated with its own thread. However, although each
card in a MultiMediaCard stack has its own individual slot, the bus architecture
prevents more than one card from being accessed at any one time. Further,
all cards in a stack must be powered up at the same time. All this suggests
that having a separate thread for each card in a multi-card slot would not
offer much benefit, and indeed would probably lead to conflicting hardware
accesses between the threads. This means that a single socket object is allocated
to represent for all cards in MultiMediaCard stack. </p> <p>The socket is
the highest level object in the MultiMediaCard controller, and is an instance
of a <xref href="GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7.dita"><apiname>DMMCSocket</apiname></xref> class. It oversees the power supply functionality,
the media change functionality, and the object that controls access to the
card stack. </p> <p>You can define and implement a derived class in the variant
DLL, <filepath>epbusmv.dll</filepath>, although it may rarely be necessary. </p> <p id="GUID-F3455C81-8A2D-557F-B3C0-6116B4756960"><b>The stack</b> </p> <p>Access
to the card stack is handled by an instance of a <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita"><apiname>DMMCStack</apiname></xref> class,
and is owned by the socket. The <codeph>DMMCStack</codeph> class is designed
to implement the set of "macros" defined by the MultiMediaCard Association.
These "macros" are a predefined set of command sequences that perform complex
bus operations. </p> <p>You will normally define and implement a derived class
in the variant DLL, <filepath>epbusmv.dll</filepath>. </p> <p id="GUID-55C54B59-3502-5338-8DD5-EC0488B53B8B"><b>The session</b> </p> <p>A
session is an instance of a <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita"><apiname>DMMCSession</apiname></xref> class, and represents
a unit of work for the MMC stack. It is, in effect, the main client interface
to the MultiMediaCard Controller. Each client (i.e. the MultiMediaCard media
driver or any other device driver) creates its own instance of this class.
The client can then make MultiMediaCard requests on the stack by putting the
appropriate information into the session object (configuring the session),
and then submitting this session object to the stack; this is also referred
to as engaging the session, and is invoked 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>.
Once submitted, the session is then scheduled - see <xref href="GUID-28844FE0-AE0F-531C-826E-CDA8400A0581.dita">Sessions
and Request Management</xref> for more background information on this. </p> <p>The <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita"><apiname>DMMCSession</apiname></xref> class
contains functions for initiating macro functions as laid down by the MultiMediaCard
Association as well as lower level functions that allow a client to control
the stack in a more explicit manner. </p> <p id="GUID-65EAFEA0-74A4-514C-82B8-9BD7A4D34FB3"><b>Power supply unit</b> </p> <p>The
behaviour of the power supply unit (PSU) is represented by the <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita"><apiname>DMMCPsu</apiname></xref> class. </p> <p>You
will normally define and implement a derived class in the variant DLL, <filepath>epbusmv.dll</filepath>. </p> <p><b> Media change</b> </p> <p>The behaviour that deals with media change events
is represented by the <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita"><apiname>DMMCMediaChange</apiname></xref> class. </p> <p>You
will normally define and implement a derived class in the variant DLL, <filepath>epbusmv.dll</filepath>. </p> <p id="GUID-26CFDD03-A4C4-5C96-88D4-5E750FDF69A3"><b>The controller factory</b> </p> <p>The
controller factory, also known as the controller interface, is a <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita"><apiname>TMMCardControllerInterface</apiname></xref> derived
class that creates instances of your platform specific: stack class, power
supply unit class, socket class, and media change class. It also allows you
to perform platform specific initialisation. </p> <p>You create an instance
of your factory class in the kernel extension entry point code in your DLL.
This normally calls <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-2C6EA849-1B62-3158-A328-DB2A7149346C"><apiname>TMMCardControllerInterface::Create()</apiname></xref> on
the object, a Symbian OS supplied function, which calls your implementations
of the <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita"><apiname>TMMCardControllerInterface</apiname></xref> pure virtual functions,
to create the instances of your classes. </p> <p>Note that these functions
are only called for sockets that are associated with MultiMediaCard devices. <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-2C6EA849-1B62-3158-A328-DB2A7149346C"><apiname>TMMCardControllerInterface::Create()</apiname></xref> iterates
through all possible socket numbers, from 0 to <xref href="GUID-2C5A5F8F-381C-3B99-AADE-44474E629CC4.dita"><apiname>KMaxPBusSockets</apiname></xref>,
calling <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-5EC9F2EE-5D14-37F9-9EFE-95BD1062C681"><apiname>TMMCardControllerInterface::IsMMCSocket()</apiname></xref> for each
socket number to determine whether the socket number is a MultiMediaCard socket. </p> <fig id="GUID-BB5C198A-D635-5F91-9987-79394F270CEC">
<image href="GUID-13664BB9-7D05-594E-95D4-49C0D31D3734_d0e383410_href.png" placement="inline"/>
</fig> </section>
</conbody></concept>