Initial contribution of the Adaptation Documentation.
<?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-E55B4FE5-517C-5A23-8ACA-E28EE202330B" xml:lang="en"><title>Platform
Specific Layer Implementation</title><shortdesc>Describes how to implement the Platform Specific Layer of the MMC
Controller. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-4C6CA873-A798-5C79-8838-0CC3C9E914FB"><title>DMMCStack derived
class</title> <p>This class controls access to the MultiMediaCard stack. This
class has a number of pure virtual functions that need to be implemented in
your Variant DLL. The diagram at <xref href="GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF.dita#GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF/GUID-92F5EBE4-C9AD-5D9A-A80E-9AFD1A09B6B3">MultiMediaCard
controller basic structure</xref> shows the class in context. </p> <p>There
is one virtual function with a default implementation that needs to be overridden. </p> <ul>
<li id="GUID-01ABEA80-002F-5490-B90F-3AE83927220B"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-0B55A650-E9ED-56CB-B06F-B1113ACDF282">Init()</xref> </p> </li>
<li id="GUID-04245FCC-D55A-5840-98CC-2113E7B6D9E4"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-CEF0EDF7-4B33-5452-8635-51C5319F78AE">MachineInfo()</xref> </p> </li>
<li id="GUID-C5C86175-9100-5687-96EB-F4AEAF0CE161"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-F41EA0A6-1CBF-5AE2-9C66-DD6E3B7312E0">ProgramPeriodInMilliSeconds()</xref> </p> </li>
<li id="GUID-12B3B751-9EFE-5273-844B-A18D99E2A7FF"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-A7EC6536-3822-58C8-9A65-B71FDDBA10F3">AdjustPartialRead()</xref> </p> </li>
<li id="GUID-AF40CF60-918D-5D9D-96C3-D96FDAD94B85"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-8A3E9782-C8D4-562D-9470-5CCE0ED1C303">GetBufferInfo()</xref> </p> </li>
<li id="GUID-60AC1F94-4936-5AB1-B31E-CEDBDE59E08E"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-BC742EB6-7063-5D00-B422-96B3772605D5">SetBusConfigDefaults()</xref> </p> </li>
<li id="GUID-592CDEF6-F450-572A-878E-077ED633C621"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-49DF2E60-AE31-502E-B7CB-694AFAF69F1B">InitClockOff()</xref> </p> </li>
<li id="GUID-82080A27-BCB7-5EC3-8F3E-2C1CDEDCA601"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-0DF60D11-AAD6-59E2-AE81-16E0DF96291B">ASSPDisengage()</xref> </p> </li>
<li id="GUID-5E0E9EC9-742A-5265-9429-C52B60D83863"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-99AC4F3B-E273-515E-8690-983E98E17256">ASSPReset()</xref> </p> </li>
<li id="GUID-DA38EA59-0A91-5498-9B3A-1F17D4511EFC"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-6EEE7EF6-4272-5116-BCEF-A852BB7B8FBD">CardDetect()</xref> </p> </li>
<li id="GUID-9F025A5A-F303-55C8-85C4-BAC0BF0C27E4"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-3F34865D-5B16-5F53-AF9E-9F52DB5D0FB5">WriteProtected()</xref> </p> </li>
<li id="GUID-D1B3A73F-E3AC-55C6-84E4-11A2AA9C3A7F"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-65547330-E112-55F2-AD4A-9B9CA5617E33">DoPowerDown()</xref> </p> </li>
<li id="GUID-4117DD14-59D4-5257-AAAD-79498391979E"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-C8C15101-4614-5DEC-A620-6EAE8EC463ED">DoPowerUpSM()</xref> </p> </li>
<li id="GUID-D93B8DEC-CFA0-5FC9-AF46-81A3B21F3545"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-C976320E-80FF-50F8-A882-F89C74F76ED3">InitClockOnSM()</xref> </p> </li>
<li id="GUID-F6BB7D3C-8A9A-5228-88ED-2F28980373D8"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-FABAED76-FC63-577B-9436-DC7C8978E2AE">IssueMMCCommandSM()</xref> </p> </li>
</ul> <p id="GUID-0B55A650-E9ED-56CB-B06F-B1113ACDF282"><b>Init()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-43A06EF7-FA7B-3653-97B4-B04336E3EB54"><apiname>DMMCStack::Init()</apiname></xref> </p> <p>The
function is intended to initialize the stack, and is called during initialization
of the MultiMediaCard controller Variant DLL from <xref href="GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7.dita#GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7/GUID-18825E56-F155-38D0-A4DF-A7C57D73C1EF"><apiname>DMMCSocket::Init()</apiname></xref>: </p> <p>You
will almost certainly need to provide your own implementation to perform any
platform-specific MultiMediaCard stack initialization. Whatever your implementation
provides, <i>it is important that you call the base class function from within
your derived version</i>. </p> <p>Return <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> if initialization
is successful, otherwise return one of the system-wide error codes to indicate
initialization failure. Note that returning a value other than <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> will
cause the kernel to panic and to fail to boot. </p> <p>You will allocate a
data transfer buffer here. The MultiMediaCard media driver needs a memory
buffer to perform data transfer operations. Where supported, DMA is generally
used to do this, and requires physically contiguous memory. However, the media
driver is created each time a card is inserted into a machine and destroyed
when the card is removed, and giving the media driver the responsibility for
allocating the memory buffer means that it might not always be possible to
allocate physically contiguous pages for it as memory becomes fragmented over
time. </p> <p>The MultiMediaCard media driver uses the <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-8A3E9782-C8D4-562D-9470-5CCE0ED1C303">GetBufferInfo()</xref> function each time it is created to get a pointer
to the buffer, and to get its length. </p> <p>Although the MultiMediaCard
media driver only expects a single buffer, it actually uses this as two separate
buffers: </p> <ul>
<li id="GUID-21E69407-DEB2-5DBE-9614-ADFF7DBF06B6"><p>a minor buffer which
must have at least enough space for the MBR (512 bytes) </p> </li>
<li id="GUID-1FF25456-0CE3-582C-9FEC-B5913C1E437A"><p>a cache buffer to cache
data blocks from the card. </p> </li>
</ul> <p>The ideal size of the cache buffer depends on the characteristics
of the card present at the time, and it is possible to customize the MultiMediaCard
controller at the platform specific layer for a particular card. </p> <p>The
following example code allocates a physically contiguous buffer - a minor
buffer size of one block is allocated together with a cache buffer size of
eight blocks. The whole buffer is then rounded up to a whole number of memory
pages. </p> <codeblock id="GUID-B01B50BE-6574-5A81-BA25-8FDFEB2C5620" xml:space="preserve">// The constant calculations could be explicitly folded, but this illustrates
// how the values are derived.
const TUint blkSzLog2 = 9;
const TUint blkSz = 1 << blkSzLog2;
const TInt minorBufLen = Max(KDiskSectorSize, blkSz);
const TInt KMinBlocksInBuffer = 8;
const TInt cchBufLen = KMinBlocksInBuffer << blkSzLog2;
TInt totalBufLen = minorBufLen + cchBufLen;
// Allocate contiguous physical memory
totalBufLen = Kern::RoundToPageSize(totalBufLen);
TPhysAddr physAddr = 0;
r = Epoc::AllocPhysicalRam(totalBufLen, physAddr);
__KTRACE_OPT(KHARDWARE, Kern::Printf("mmc:ini:physical = %08x", physAddr));
if (r != KErrNone)
{
return r;
}
DPlatChunkHw* bufChunk = NULL;
r = DPlatChunkHw::New(bufChunk, physAddr, totalBufLen, EMapAttrCachedWBRA|EMapAttrSupRw);
if(r != KErrNone)
{
if (physAddr)
{
Epoc::FreePhysicalRam(physAddr, totalBufLen);
}
return r;
}
iMDBuf = reinterpret_cast<TUint8*>(bufChunk->LinearAddress());
iMDBufLen = totalBufLen;
</codeblock> <p id="GUID-CEF0EDF7-4B33-5452-8635-51C5319F78AE"><b>MachineInfo()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-3E5532A5-4645-3F77-A7A9-7AFF334FA5A4"><apiname>DMMCStack::MachineInfo()</apiname></xref> </p> <p>The
function returns configuration information for the MultiMediaCard stack. </p> <p>The
function takes a reference to a <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita"><apiname>TMMCMachineInfo</apiname></xref> object,
and your implementation must fill the public data members of the object. </p> <p id="GUID-F41EA0A6-1CBF-5AE2-9C66-DD6E3B7312E0"><b>ProgramPeriodInMilliSeconds()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-C0998F1F-EE3B-32C1-9898-288EA1D71AC0"><apiname>DMMCStack::ProgramPeriodInMilliSeconds()</apiname></xref> </p> <p>When a data block is written to a card, the data is read into an
internal buffer on the card and is then programmed into the payload memory.
While the card is in <i>programming mode</i>, it cannot be read from, or written
to, but it is possible to query its status using CMD13. </p> <p>Immediately
after a block of data is written by <codeph>CIMReadWriteBlocksSM()</codeph>,
the MultiMediaCard controller requests the card's state using CMD13. If the
card is still in the programming state, then the state machine <codeph>ProgramTimerSM()</codeph> launches
a timer with the period returned by <codeph>ProgramPeriodInMilliSeconds()</codeph>.
The state of the card is periodically checked until it is no longer in programming
mode. </p> <p>For platforms that do not provide an interrupt to indicate when
programming mode is finished, <codeph>ProgramPeriodInMilliSeconds()</codeph> should
return the interval, in milliseconds, to be used by the poll timer. </p> <p id="GUID-A7EC6536-3822-58C8-9A65-B71FDDBA10F3"><b>AdjustPartialRead()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-7FEC1574-5448-3DF5-8BD2-AABDBD0211C3"><apiname>DMMCStack::AdjustPartialRead()</apiname></xref> </p> <p>Some
cards support a partial read feature, which is indicated by the <codeph>READ_BL_PARTIAL</codeph> bit
in the <codeph>CSD</codeph> register. When this is the case, it is possible
to read a section within a single physical block, without having to read the
entire block. </p> <p>The MultiMediaCard media driver uses this feature to
read small amounts of data more quickly. However, many hardware implementations
impose restrictions on the granularity of the data that can be read from the
card. For example, they may use a 32-bit FIFO. </p> <p>This function allows
you to enforce the limits imposed by the hardware. </p> <p>The <codeph>aStart</codeph> and <codeph>aEnd</codeph> arguments
of <codeph>AdjustPartialRead()</codeph> define the range on the card from
which the media driver would like to read. Your implementation should return
in <codeph>*aPhysStart</codeph> and <codeph>*aPhysEnd</codeph> the range that
the hardware will allow to be read. </p> <p>For example, to word align data,
the function would be implemented using the following code: </p> <codeblock id="GUID-30DE526C-70C2-5118-BFBB-72759EFC8C93" xml:space="preserve">void AdjustPartialRead(const TMMCard* aCard, TUint32 aStart, TUint32 aEnd, TUint32* aPhysStart, TUint32* aPhysEnd);
{
...
const TUint32 KWordMask = 3;
*aPhysStart = aStart & ~KWordMask;
*aPhysEnd = (aEnd + KWordMask) & ~KWordMask;
...
}
</codeblock> <p id="GUID-8A3E9782-C8D4-562D-9470-5CCE0ED1C303"><b>GetBufferInfo()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-EC9B740A-3A07-35AB-BACE-2EC1F96EEF0F"><apiname>DMMCStack::GetBufferInfo()</apiname></xref> </p> <p>The
MultiMediaCard media driver needs a memory buffer to perform data transfer
operations, and this is, typically, allocated once only by the <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-0B55A650-E9ED-56CB-B06F-B1113ACDF282">Init()</xref> function when this stack object is initialized. </p> <p>The
MultiMediaCard media driver is created each time a card is inserted into a
machine and destroyed when the card is removed, and it uses this function,
each time it is created to get a pointer to the memory buffer, and to get
its length. The MultiMediaCard media driver then uses this buffer, over its
lifetime, for data transfer operations. </p> <p id="GUID-BC742EB6-7063-5D00-B422-96B3772605D5"><b>SetBusConfigDefaults()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-C7297E13-5F78-396D-842B-FB16D3424374"><apiname>DMMCStack::SetBusConfigDefaults()</apiname></xref> </p> <p>The function returns information about the MultiMediaCard bus configuration
for this platform. </p> <p>The function takes a <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> value
containing the bus speed that the controller intends to use, and a reference
to a <xref href="GUID-C0E2780A-47B3-31A2-827C-AF89C1B65F2E.dita"><apiname>TMMCBusConfig</apiname></xref> object. The implementation of this function
must fill the public data members of this object. See the class reference
documentation for the data members. </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita"><apiname>DMMCStack</apiname></xref> has
two private data members of type <xref href="GUID-75FF770B-07D1-3C07-9577-5A37841E53E7.dita"><apiname>TMMCStackConfig</apiname></xref>: </p> <ul>
<li id="GUID-A56BF364-F02F-54EA-80F8-E4AB5E7A10C9"><p> <codeph>iMasterConfig</codeph> </p> </li>
<li id="GUID-C94FFA4E-51C7-5CBA-BFBB-F692438412FE"><p> <codeph>iConfig</codeph> </p> </li>
</ul> <p>The information returned by the call to <codeph>SetBusConfigDefaults()</codeph> is
stored in <codeph>iMasterConfig</codeph>'s <codeph>iBusConfig</codeph> private
data member. </p> <p> <codeph>iMasterConfig</codeph> contains the master bus
configuration settings for the platform. Each time a new session is made current,
the master bus configuration settings are merged with the specific bus configuration
settings for that session, (as set up in the public data member <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-73BC8CE4-593E-3BAC-909A-FB8F419895C8"><apiname>DMMCSession::iConfig</apiname></xref>),
and the result is stored in <codeph>iConfig</codeph>. It is these merged bus
configuration settings that are used to configure the hardware interface.
The platform specific layer can access these settings with a call to Master<xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-E0275614-109E-3803-A0AE-3313E1E0038B"><apiname>DMMCStack::BusConfig()</apiname></xref>. </p> <p> <codeph> SetBusConfigDefaults()</codeph> is called at two stages in the execution of the macro CIM_UPDATE_ACQ to
update the <codeph>iMasterConfig</codeph> object. </p> <ul>
<li id="GUID-5C98DB8C-60AF-5333-A250-5D6509D754E5"><p>First, it is called
at the start of the card initialization stage with the bus speed argument, <codeph>aClock</codeph>,
set to the fOD rate (400kHz). </p> </li>
<li id="GUID-0CD15184-15F8-5104-908F-612CCBCA953A"><p>Second, it is called
after the CSD registers for each card have been read with the bus speed argument, <codeph>aClock</codeph>,
set to the slowest maximum transfer rate (TRAN_SPEED) reported by any of the
CSD registers. </p> </li>
</ul> <p id="GUID-49DF2E60-AE31-502E-B7CB-694AFAF69F1B"><b> InitClockOff()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-BF94B298-7F72-33F7-A2F0-F19807BF2CDC"><apiname>DMMCStack::InitClockOff()</apiname></xref> </p> <p>Switches
from identification mode of operation to data transfer mode operation. </p> <p>When
this function is called, the clock information in the <codeph>iBusConfig</codeph> member
(see <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-BC742EB6-7063-5D00-B422-96B3772605D5">SetBusConfigDefaults()</xref>)
will not have been updated to the new data transfer rate. </p> <p>This function
should, in general, just switch from open drain to push-pull bus mode, with
the clock rate being changed at the start of <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-A48C1C16-B465-3DDA-9C83-00DEB8D27B68"><apiname>DMMCStack::IssueMMCCommandSM()</apiname></xref>,
when <codeph>iBusConfig</codeph> will be valid. </p> <p id="GUID-0DF60D11-AAD6-59E2-AE81-16E0DF96291B"><b> ASSPDisengage()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-36C720F9-DEAF-3896-A12A-2AE2581AA347"><apiname>DMMCStack::ASSPDisengage()</apiname></xref> </p> <p>This
function is called by the platform independent layer each time a session has
completed or has been aborted. </p> <p>The function gives the platform specific
layer the chance to free resources or disable any activities that were required
to perform the session. </p> <p>The implementation should not turn off the
clock to the hardware interface as this will be turned off by the inactivity
timer. Typically, the implementation disables DMA and interface interrupts,
and forces the hardware interface into idle. </p> <p>At the end of your implementation,
you must add a call <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-3DFCBE96-E9F3-3FF3-97BC-A3A3024089BD"><apiname>DMMCStack::ReportASSPDisengaged()</apiname></xref> to
report to the platform independent layer that platform specific layer resources
have been disengaged. </p> <p id="GUID-99AC4F3B-E273-515E-8690-983E98E17256"><b>ASSPReset()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-36D3F4D9-A2FC-3355-ABE0-31C9F7397E2D"><apiname>DMMCStack::ASSPReset()</apiname></xref> </p> <p>This
function is called by the platform independent layer when the current session
is being aborted, and platform specific asynchronous activity is to be cancelled.
The function may also be called by the platform specific layer as part of
the <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-65547330-E112-55F2-AD4A-9B9CA5617E33">DoPowerDown()</xref> implementation. </p> <p>The function gives the platform specific layer the chance to stop all activities
on the host stack. It will, in general, perform the same operations as <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-0DF60D11-AAD6-59E2-AE81-16E0DF96291B">ASSPDisengage()</xref> but,
in addition, will turn off the clock to the hardware interface and release
any requested power requirements made on the power model, i.e. release any
power requirements made by <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-C976320E-80FF-50F8-A882-F89C74F76ED3">InitClockOnSM()</xref>. </p> <p>At the end of your implementation, you must add a call <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-3DFCBE96-E9F3-3FF3-97BC-A3A3024089BD"><apiname>DMMCStack::ReportASSPDisengaged()</apiname></xref> to
report to the platform independent layer that platform specific layer resources
have been disengaged. </p> <p id="GUID-6EEE7EF6-4272-5116-BCEF-A852BB7B8FBD"><b>CardDetect()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-02C4D1A0-6149-389D-9F31-3E7EBF1DCA66"><apiname>DMMCStack::CardDetect()</apiname></xref> </p> <p>Implement
this function to report whether a card is present in a specified card socket. </p> <p>This
function takes a <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> value containing the card socket
that is to be queried. </p> <p id="GUID-3F34865D-5B16-5F53-AF9E-9F52DB5D0FB5"><b>WriteProtected()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-E7E97501-10E7-38E6-9F8C-2A62F260BA46"><apiname>DMMCStack::WriteProtected()</apiname></xref> </p> <p>Implement
this function to report whether a card in a specified card socket is mechanically
write protected. </p> <p>This function takes a <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> value
containing the card socket that is to be queried. </p> <p id="GUID-65547330-E112-55F2-AD4A-9B9CA5617E33"><b>DoPowerDown()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-3E90AF73-F4D3-34C5-B6D3-6BF69C6137C8"><apiname>DMMCStack::DoPowerDown()</apiname></xref> </p> <p>This
function is called as part of the bus power down sequence: </p> <ul>
<li id="GUID-E9E072D3-A2F7-5DD2-B7D9-A89840BBA914"><p>by the power model,
in power standby and power emergency standby situations </p> </li>
<li id="GUID-1EFB0616-45B9-5EC2-9456-54F7D10D2894"><p>when a door-open event
occurs </p> </li>
<li id="GUID-83F42DEB-C6EE-5558-8907-CFD141461456"><p>when the bus inactivity
timer has timed out </p> </li>
<li id="GUID-0EA77E57-E2D0-599D-8E90-ECE1D21BC329"><p>if a power supply unit
(PSU) voltage check fails. </p> </li>
</ul> <p>The function should stop all activities on the host stack, turn off
the clock to the hardware interface and release any requested power requirements
made on the power model. The function is very often implemented as a call
of <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-99AC4F3B-E273-515E-8690-983E98E17256">ASSPReset()</xref>. </p> <p>The
function should not turn off the MultiMediaCard power supply unit as this
will be performed immediately afterwards by a call to the <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita#GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B/GUID-4DF0741F-B143-3B46-82BE-9CD0261C27E5"><apiname>DMMCPsu::DoSetState()</apiname></xref> derived
class function from the platform independent layer. </p> <p id="GUID-C8C15101-4614-5DEC-A620-6EAE8EC463ED"><b> DoPowerUpSM()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-791BCA03-61F3-3C1C-BA2D-D633A94AF299"><apiname>DMMCStack::DoPowerUpSM()</apiname></xref> </p> <p>This
is a state machine function, called as a child function at the start of the <codeph>CIM_UPDATE_ACQ</codeph> macro
state machine. </p> <p>The function should perform the necessary platform
specific actions associated with powering up the bus. This includes turning
on the MultiMediaCard PSU. However, the hardware interface clock should <i>not</i> be
turned on as part of this function. </p> <p>If the controller has to request
power resources from the power model, e.g. where a fast system clock is required
all the time the bus is powered, then this state machine function can be used
to wait asynchronously for this resource to become available. </p> <p>If the
activity performed by this function completes successfully: </p> <ul>
<li id="GUID-7C64DB32-139B-5F45-9F2C-6693F9E16F83"><p>it must call <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-40973A35-3A73-3DBD-9EB7-99CE55E6D694"><apiname>DMMCStack::ReportPowerUp()</apiname></xref>. </p> </li>
<li id="GUID-42E872B5-EA6A-5901-AD93-5F9B99C81D69"><p>it returns <xref href="GUID-E7D46003-E502-39D1-AF52-83B87AE6930B.dita"><apiname>KMMCErrNone</apiname></xref>. </p> </li>
</ul> <p>The function should return <xref href="GUID-E7D46003-E502-39D1-AF52-83B87AE6930B.dita"><apiname>KMMCErrNone</apiname></xref> if it completes
successfully or one of the other <xref href="GUID-FF4AB1CF-7A2C-3FC6-B123-D6819E1BCDCA.dita"><apiname>TMMCErr</apiname></xref> error codes. </p> <p>See
the general background information on <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita">the
state machine</xref>. </p> <p id="GUID-C976320E-80FF-50F8-A882-F89C74F76ED3"><b>InitClockOnSM()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-7B91EF52-26E5-333C-A037-B142B492BCC4"><apiname>DMMCStack::InitClockOnSM()</apiname></xref> </p> <p>This
is a state machine function, called as part of the <codeph>CIM_UPDATE_ACQ</codeph> macro
state machine. </p> <p>The function should turn on the clock to the hardware
interface. The function is so named because this clock is always first turned
on at the identification mode frequency. </p> <p>The function is implemented
as a state machine function because it may be necessary to include a short
delay after the clock has been turned on to allow it to stabilize. </p> <p>If
it is necessary for the MultiMediaCard controller to request any power resources
from the power model on this platform, for example, requesting a necessary
system clock, then it should be performed as part of this function. In some
cases, it may be necessary to wait for this power resource to become available. </p> <p>At
the <i>beginning</i> of your implementation, you must add a call <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-D797747A-0AF6-36B1-BD92-3D6950A3B7B4"><apiname>DMMCStack::ReportASSPEngaged()</apiname></xref> to
report to the platform independent layer that platform specific layer resources
have been engaged. </p> <p>The function should return <xref href="GUID-E7D46003-E502-39D1-AF52-83B87AE6930B.dita"><apiname>KMMCErrNone</apiname></xref> if
it completes successfully or one of the other <xref href="GUID-FF4AB1CF-7A2C-3FC6-B123-D6819E1BCDCA.dita"><apiname>TMMCErr</apiname></xref> error
codes. </p> <p>Note: </p> <ul>
<li id="GUID-2474710D-C595-5331-9182-A2EF97A1EB27"><p>the function is only
called once for each invocation of the CIM_UPDATE_ACQ macro and the important
thing to stress is that the interface clock is being turned on after a period
when it has been off, and therefore often requires time to stabilize. </p> </li>
<li id="GUID-FE92334D-757D-5C08-AF98-9E0912BA2820"><p>In the course of executing
a session, the MultiMediaCard controller may switch the clock more than once
between the identification mode frequency and the data transfer mode frequency,
but this function only ever gets called once. </p> </li>
</ul> <p>See the general background information on <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita">the
state machine</xref>. </p> <p id="GUID-FABAED76-FC63-577B-9436-DC7C8978E2AE"><b> IssueMMCCommandSM()</b> </p> <p> <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-A48C1C16-B465-3DDA-9C83-00DEB8D27B68"><apiname>DMMCStack::IssueMMCCommandSM()</apiname></xref> </p> <p>This
is a <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita">state machine</xref> function
that executes a single command over the bus. The implementation of this function
is an important part in the process of porting the MultiMediaCard controller. </p> <p>The
input parameters for the command are passed via the current command descriptor,
an instance of the <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita"><apiname>TMMCCommandDesc</apiname></xref> class, on the session’s
command stack. The parameters contain information such as: the type of command,
the response type, the command arguments, the data source/destination for
data transfer commands etc. Use <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-931547BD-665D-326A-92B5-909B2D57F8C6"><apiname>DMMCSession::Command()</apiname></xref> to
get the current command descriptor. </p> <p>Information about the command
response, the number of bytes transferred etc., is passed back using the same
command descriptor. Specifically, the platform independent layer relies on
responses to the following commands being returned in the <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-86553172-AE4E-3707-A0D2-8C2BB8880253"><apiname>TMMCCommandDesc::iResponse</apiname></xref> member,
in big-endian format: </p> <ul>
<li id="GUID-45605105-B91A-506B-A0F9-A317CA84D5EF"><p>Returns the OCR register
value in response to a SEND_OP_COND command (CMD1). Note that there is <i>no
CRC</i> with this response. Your code should ignore any CRC failure indication
from the MultiMediaCard controller hardware, and just copy the response into <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-86553172-AE4E-3707-A0D2-8C2BB8880253"><apiname>TMMCCommandDesc::iResponse</apiname></xref>. </p> </li>
<li id="GUID-3E8B7D20-71F1-5609-8A16-24C6E2A7186A"><p>Returns the CID register
value in response to an ALL_SEND_CID command (CMD2) and a SEND_CID command
(CMD10). </p> </li>
<li id="GUID-8D051F10-65BB-57AF-8B75-247829DC239A"><p>Returns the CSD register
value in response to a SEND_CSD command (CMD9). </p> </li>
<li id="GUID-C899645F-8478-57BF-8E1E-58AC50EB9FE3"><p>Returns the card status
in response to all R1 and R1b commands. </p> </li>
</ul> <p>Note that you can use the functions <xref href="GUID-32036692-8BA3-3AAF-9FD8-D135DFADAE77.dita#GUID-32036692-8BA3-3AAF-9FD8-D135DFADAE77/GUID-D2EFC17B-FC2E-3FDC-AE7A-E2AA109D4B40"><apiname>TMMC::BigEndian4Bytes()</apiname></xref> and
TMC::to help with conversion to big-endian format. </p> <p>The function should
return <xref href="GUID-E7D46003-E502-39D1-AF52-83B87AE6930B.dita"><apiname>KMMCErrNone</apiname></xref> if it completes successfully or one
of the other <xref href="GUID-FF4AB1CF-7A2C-3FC6-B123-D6819E1BCDCA.dita"><apiname>TMMCErr</apiname></xref> error codes. </p> <p>See also background
information: </p> <ul>
<li id="GUID-0667980A-4A9E-5BD0-952E-97AD4C83B939"><p> <xref href="GUID-C059F39F-BC53-5C92-B05E-863B8CF22859.dita">Issuing
commands</xref> </p> </li>
<li id="GUID-DF2B96DD-DD85-52C2-9EC8-30379E03D1DA"><p> <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita">The
state machine</xref>. </p> </li>
</ul> </section>
<section id="GUID-3A1E907E-A74D-59CB-A1D6-FEF4849EF2D5"><title>DMMCPsu derived
class</title> <p>This class controls the MultiMediaCard socket's power supply.
A class needs to be derived from this in the platform specific layer to handle
the Variant specific functionality of the power supply. </p> <p>This class
has a number of pure virtual functions that need to be implemented in your
Variant DLL. The diagram at <xref href="GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF.dita#GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF/GUID-92F5EBE4-C9AD-5D9A-A80E-9AFD1A09B6B3">MultiMediaCard
controller basic structure</xref> shows the class in context. </p> <p>There
is one virtual function with an empty default implementation that needs to
be overridden. </p> <ul>
<li id="GUID-025272EF-9DE8-5975-8993-006EE4D56E80"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-6EB8EF1C-BCCB-54A1-8CBA-4E8A2A20CABE">DoCreate()</xref> </p> </li>
<li id="GUID-6BAFE3AA-6CCA-581B-A96C-D1FD89D1D8CD"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-99529E84-17E1-5F23-9A1B-EBE3976D9B14">PsuInfo()</xref> </p> </li>
<li id="GUID-7419D681-D0CC-5CA7-8EE7-0D5A20779921"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-5809318D-E3E1-5261-AABA-604EBE72523F">DoSetState()</xref> </p> </li>
<li id="GUID-E570E830-B57E-5A39-9EF1-CF68F3853AFF"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-B5030D2E-A466-596C-A2C3-73F38CF9C1A7">DoCheckVoltage()</xref> </p> </li>
</ul> <p id="GUID-6EB8EF1C-BCCB-54A1-8CBA-4E8A2A20CABE"><b>DoCreate()</b> </p> <p> <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita#GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B/GUID-32771B9D-D2B8-33F5-AFC5-4476165C0A76"><apiname>DMMCPsu::DoCreate()</apiname></xref> </p> <p>The
function is intended to perform hardware initialization on the MultiMediaCard
power supply, for example, setting port direction registers. </p> <p>The function
is called after creation of the <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita"><apiname>DMMCPsu</apiname></xref> derived class instance,
which is done during kernel initialization when the MultiMediaCard controller
Variant DLL extension is loaded. </p> <p>The function has a default implementation
that just returns <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> <p>Your implementation
should <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> if the hardware initialization is successful,
otherwise it should return one of the system-wide error codes to indicate
initialization failure. Note that returning a value other than <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> will
cause the kernel to panic and to fail to boot. </p> <p id="GUID-99529E84-17E1-5F23-9A1B-EBE3976D9B14"><b>PsuInfo()</b> </p> <p> <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita#GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B/GUID-C7600EDA-B564-31E2-835C-9C580A29FC1D"><apiname>DMMCPsu::PsuInfo()</apiname></xref> </p> <p>The
function returns information about the MultiMediaCard power supply. </p> <p>The
function takes a reference to a <xref href="GUID-E3BB783F-423F-352A-9B6E-FD23EC80AA8D.dita"><apiname>TPBusPsuInfo</apiname></xref> object, and
your implementation must fill the public data members of the object. </p> <p>Note: </p> <ul>
<li id="GUID-B8527FE4-61BB-574A-A200-5EA083A76A6D"><p>You can use the constant <xref href="GUID-3B63FFD6-AE21-366A-B435-AE6213AA2EE0.dita"><apiname>KMMCAdjustableOpVoltage</apiname></xref> to
set bit 31 in <xref href="GUID-E3BB783F-423F-352A-9B6E-FD23EC80AA8D.dita#GUID-E3BB783F-423F-352A-9B6E-FD23EC80AA8D/GUID-6B1E1CDD-A0E7-3AA5-989E-8D7A199ADE2A"><apiname>TPBusPsuInfo::iVoltageSupported</apiname></xref>. </p> </li>
<li id="GUID-694DB272-C66E-5392-8C7E-DC1B875E9DD3"><p>Set <xref href="GUID-E3BB783F-423F-352A-9B6E-FD23EC80AA8D.dita#GUID-E3BB783F-423F-352A-9B6E-FD23EC80AA8D/GUID-8C9792BC-8FAA-3DE5-8032-7546887FA8FB"><apiname>TPBusPsuInfo::iNotLockedTimeOut</apiname></xref> to
0. </p> </li>
</ul> <p id="GUID-5809318D-E3E1-5261-AABA-604EBE72523F"><b> DoSetState()</b> </p> <p> <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita#GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B/GUID-4DF0741F-B143-3B46-82BE-9CD0261C27E5"><apiname>DMMCPsu::DoSetState()</apiname></xref> </p> <p>The
function is called to turn the PSU on or off. </p> <p>The requested state
of the PSU depends on the <xref href="GUID-CD00D507-CC86-33BE-91A7-FAF7EAFD4840.dita"><apiname>TPBusPsuState</apiname></xref> value passed to
it. </p> <p>If the PSU supports voltage adjustment, rather than a single fixed
value, then the required voltage setting is contained in the protected data
member <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita#GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B/GUID-7A625108-D5AE-301F-9CAB-2625DAD0C0B0"><apiname>DMMCPsu::iVoltageSetting</apiname></xref>. </p> <p>Note that the
stack may call this function to request the power to be turned on when it
is already on. You should check for this and do nothing if the power is already
in the requested state. </p> <p id="GUID-B5030D2E-A466-596C-A2C3-73F38CF9C1A7"><b>DoCheckVoltage()</b> </p> <p> <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita#GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B/GUID-17AC2A1C-5430-38B1-BD3F-966CE4936940"><apiname>DMMCPsu::DoCheckVoltage()</apiname></xref> </p> <p>The
function is called to check that the voltage level of the PSU is as expected. </p> <p>Checking
the voltage level may be a long running operation (e.g. using an ADC), and
it may not always be appropriate to perform and complete the check directly
within this function. </p> <p>When voltage checking is complete, either synchronously
in this function, or asynchronously at some later stage, the result should
be returned by calling the base class function <xref href="GUID-A8B5FB5A-4709-3F29-B2CB-81FC5B0E7D63.dita#GUID-A8B5FB5A-4709-3F29-B2CB-81FC5B0E7D63/GUID-5643935F-9E97-35B0-9D92-88CA613F0016"><apiname>DPBusPsuBase::ReceiveVoltageCheckResult()</apiname></xref>.
Pass <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> to indicate a successful check; pass <xref href="GUID-A94AC24A-EADF-3913-8345-708ED637968E.dita"><apiname>KErrGeneral</apiname></xref> to
indicate a failed check. </p> <p>Note that this function is not called as
part of <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-791BCA03-61F3-3C1C-BA2D-D633A94AF299"><apiname>DMMCStack::DoPowerUpSM()</apiname></xref> processing, which means
that it is not possible to use this function to introduce a delay until power
is stable when the PSU is turned on. If such a delay is required while the
power lines stabilize, then it will be necessary to make this function part
of the DoPowerUpSM state machine. </p> </section>
<section id="GUID-C80E57B1-933B-55D7-949B-E68DB9B96B94"><title>DMMCMediaChange
derived class</title> <p>This class provides support for dealing with media
change events, i.e. the insertion and removal of removable media. </p> <p>A
class needs to be derived from this in the platform specific layer to handle
the Variant specific functionality. </p> <p>This class has a number of pure
virtual functions that need to be implemented in your Variant DLL. The diagram
at <xref href="GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF.dita#GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF/GUID-92F5EBE4-C9AD-5D9A-A80E-9AFD1A09B6B3">MultiMediaCard
controller basic structure</xref> shows the class in context. </p> <p>There
is one virtual function with an empty default implementation that needs to
be overridden. </p> <ul>
<li id="GUID-1BAEFE73-3B73-5BA7-872D-89C3B3F8BF75"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-BFC23CC1-102F-5740-A608-CF91C2BC3897">Create()</xref> </p> </li>
<li id="GUID-C1235A87-68BB-5AF4-80F6-DFB7DBA8432C"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-726A2A5F-18D3-55BD-9B92-0676266794C6">MediaState()</xref> </p> </li>
<li id="GUID-BBAEC56C-DBA7-586C-A9CC-1E4E70A81096"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-1ADD0F5A-B561-54AE-BB2F-81AC3E8D81A4">DoDoorOpen()</xref> </p> </li>
<li id="GUID-22D6992C-868B-5E18-9AA0-624EA51DB529"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-58829228-43A9-546B-8CFD-31DF8FBB0078">DoDoorClosed()</xref> </p> </li>
<li id="GUID-04B7E650-7DA8-5F61-9D8E-89FC2B93AE20"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-F91B9434-5B90-5221-B5E6-D57F50391D81">ForceMediaChange()</xref> </p> </li>
</ul> <p id="GUID-BFC23CC1-102F-5740-A608-CF91C2BC3897"><b>Create()</b> </p> <p> <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita#GUID-2F974AD8-551B-35F0-B72C-99122913714D/GUID-F96EF34B-7B38-37DC-9B34-E0D4D1963622"><apiname>DMMCMediaChange::Create()</apiname></xref> </p> <p>The
function is intended to perform hardware initialization on the MultiMediaCard
media change hardware, for example, setting port direction registers, binding
to the door open interrupt etc. </p> <p>The function is called after creation
of the <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita"><apiname>DMMCMediaChange</apiname></xref> derived class instance, which is
done during kernel initialization when the MultiMediaCard controller Variant
DLL extension is loaded. </p> <p>The function has a default implementation
that just returns <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>. </p> <p>Your implementation
should return <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> if the hardware initialization is
successful, otherwise it should return one of the system-wide error codes
to indicate initialization failure. Note that returning a value other than <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> will
cause the kernel to panic and to fail to boot. </p> <p id="GUID-726A2A5F-18D3-55BD-9B92-0676266794C6"><b> MediaState()</b> </p> <p> <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita#GUID-2F974AD8-551B-35F0-B72C-99122913714D/GUID-A951EF31-83F1-3E07-A5BD-5342B6125ACF"><apiname>DMMCMediaChange::MediaState()</apiname></xref> </p> <p>The
function should return the current state of the media, i.e. whether the media
door is open or closed. To indicate the state, it should return one of the <xref href="GUID-49F96729-2DDB-37E0-AE39-9BEF2B7FF7F9.dita"><apiname>TMediaState</apiname></xref> enum
values. </p> <p id="GUID-1ADD0F5A-B561-54AE-BB2F-81AC3E8D81A4"><b>DoDoorOpen()</b> </p> <p> <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita#GUID-2F974AD8-551B-35F0-B72C-99122913714D/GUID-6F734353-3458-3A8B-93E7-317674A1CAA4"><apiname>DMMCMediaChange::DoDoorOpen()</apiname></xref> </p> <p>This
function should handle a media door open event. What needs to be done depends
on how door open and door closed events are detected. </p> <p>The most common
pattern is where the platform hardware is capable of generating an interrupt
when a door open event occurs, but cannot generate an interrupt when a door
closed event occurs. In this situation, the hardware provides a readable door
status that can be checked for the door closed state on a periodic basis (i.e.
polling). </p> <p>Assuming this, <codeph>DoDoorOpen()</codeph> would need
to enable a tick timer to poll for the door closing. The timer callback function
would check the state of the door, and if this showed a closed door, the timer
would be disabled and the function <xref href="GUID-C122D579-BB08-3084-A30E-DC857D6E7282.dita#GUID-C122D579-BB08-3084-A30E-DC857D6E7282/GUID-4F53C9F7-89C5-3CB6-A3D5-7DF40DAFF37F"><apiname>DMediaChangeBase::DoorClosedService()</apiname></xref> called.
This results in a call to <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-58829228-43A9-546B-8CFD-31DF8FBB0078">DoDoorClosed()</xref>. </p> <p>Note that the door open interrupt is cleared before this function is
called. The interrupt results in a call to <xref href="GUID-C122D579-BB08-3084-A30E-DC857D6E7282.dita#GUID-C122D579-BB08-3084-A30E-DC857D6E7282/GUID-6197984B-3884-367B-AE91-8E7E25203C95"><apiname>DMediaChangeBase::DoorOpenService()</apiname></xref>,
which in turn results in a call to this function <codeph>DoDoorOpen()</codeph>. </p> <p>Your
implementation would necessarily be different if an open door event could
not be signalled by an interrupt and a tick timer were to be used to poll
for an open door status. </p> <p id="GUID-58829228-43A9-546B-8CFD-31DF8FBB0078"><b>DoDoorClosed()</b> </p> <p> <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita#GUID-2F974AD8-551B-35F0-B72C-99122913714D/GUID-F26714BC-6648-349D-812D-6FD911602754"><apiname>DMMCMediaChange::DoDoorClosed()</apiname></xref> </p> <p>This
function should handle a media door closed event. What needs to be done depends
on how door open and door closed events are detected. </p> <p>The most common
pattern is where the platform hardware is capable of generating an interrupt
when a door open event occurs, but cannot generate an interrupt when a door
closed event occurs. In this situation, the hardware provides a readable door
status that can be checked for the door closed state on a periodic basis (i.e.
polling). </p> <p>Assuming this, <codeph>DoDoorClosed()</codeph> would be
called by the timer callback function established by <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-1ADD0F5A-B561-54AE-BB2F-81AC3E8D81A4">DoDoorOpen()</xref> when the door status indicates a closed door; the function
would need to re-enable the door open interrupt. </p> <p>Your implementation
would necessarily be different if a closed door event were to be signalled
by an interrupt. </p> <p id="GUID-F91B9434-5B90-5221-B5E6-D57F50391D81"><b> ForceMediaChange()</b> </p> <p> <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita#GUID-2F974AD8-551B-35F0-B72C-99122913714D/GUID-2DB81D37-C930-3B3C-A64E-B734039A2C95"><apiname>DMMCMediaChange::ForceMediaChange()</apiname></xref> </p> <p>This function is called by the local media device driver to force a remount
of the media device. For example to reopen a media driver in secure mode. </p> <p>It
should result in the same sequence of operations as would occur if a door
open event had taken place; for example, disabling the door open interrupt
and calling <xref href="GUID-C122D579-BB08-3084-A30E-DC857D6E7282.dita#GUID-C122D579-BB08-3084-A30E-DC857D6E7282/GUID-6197984B-3884-367B-AE91-8E7E25203C95"><apiname>DMediaChangeBase::DoorOpenService()</apiname></xref>. </p> </section>
<section id="GUID-7E709B21-8D38-5041-846F-CB7983B66834"><title>TMMCardControllerInterface
derived class (The factory class)</title> <p>This is a class, also known as <xref href="GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF.dita#GUID-BE6AFD38-5952-537F-848C-C76C8F5FA9BF/GUID-26CFDD03-A4C4-5C96-88D4-5E750FDF69A3">the
controller factory</xref> that is responsible for deciding which peripheral
bus sockets are sockets that have been designated as a MultiMediaCard sockets
on this platform. It is also responsible for creating the platform-specific
layer objects associated with those MultiMediaCard sockets, i.e. the DMMCSocket,
DMMCStack, DMMCMediaChange, and DMMCPsu objects. </p> <p>This class defines
a number of pure virtual functions that need to be implemented in your Variant
DLL to provide the functionality that is specific to your platform. </p> <p>An
instance of your <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita"><apiname>TMMCardControllerInterface</apiname></xref> derived class
is created in the <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-732EDE1D-452A-5A48-B5DB-1196C5F8BEBD">Variant
DLL entry point code</xref>. </p> <ul>
<li id="GUID-61BF196A-EFD3-57E1-98C2-A5B6350AC82E"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref> </p> </li>
<li id="GUID-0FED2860-6710-517D-BB60-7FCBD043CEFB"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-829E686F-58F9-56A9-9EC4-CD59B14E127B">NewSocket()</xref> </p> </li>
<li id="GUID-3213A9CF-3155-513D-9F29-AB573018F23B"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-E0F612EB-85BC-533D-A71C-3FC93D9CC708">NewStack()</xref> </p> </li>
<li id="GUID-9C8219D2-67EF-55B0-B01E-ACB2B0AC63CB"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-33A9C3DE-80EF-5895-BC7D-EA2ED6EB083B">MediaChangeID()</xref> </p> </li>
<li id="GUID-B8309E5D-7F8A-5B62-81B3-6679AFBC9319"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-6B1FE81F-1497-5447-9286-B0BE54AE6831">NewMediaChange()</xref> </p> </li>
<li id="GUID-62725219-BAD2-528E-BC6A-84ACBA0A5C87"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-E969F613-01A3-54A7-8CC6-67F4A8E9558F">VccID()</xref> </p> </li>
<li id="GUID-67AE2495-BCF2-51B6-9F52-78FA36A65F2A"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-083F38DB-AC65-5257-B169-2099194D3082">NewVcc()</xref> </p> </li>
<li id="GUID-428FA30E-1E9A-50EA-BE3F-02E9B279E868"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-81A8BF8E-FB8B-596D-8C9A-690CD6449C12">Init()</xref> </p> </li>
</ul> <p id="GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA"><b>IsMMCSocket()</b> </p> <p> <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> </p> <p>Implement this function to indicate whether the peripheral bus socket, as
identified by the specified peripheral bus socket number, is designated as
a MultiMediaCard socket on this platform. It should return <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> if
the socket has been so designated, and return <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref> if
not. </p> <p>The function is called from <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>,
which passes a socket number that can fall into the range 0 to <xref href="GUID-2C5A5F8F-381C-3B99-AADE-44474E629CC4.dita"><apiname>KMaxPBusSockets</apiname></xref>. </p> <p>Internally,
Symbian platform reserves space for an array of pointers to <xref href="GUID-C988CAE6-9073-3851-A0B0-5479D1A34CFB.dita"><apiname>DPBusSocket</apiname></xref> objects,
and this function allows the platform specific layer to identify which slot
is to be used for the <xref href="GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7.dita"><apiname>DMMCSocket</apiname></xref> object. </p> <codeblock id="GUID-F1E0478A-8CE8-5E2F-87F8-AAFCCCE8A042" xml:space="preserve">GLDEF_D DPBusSocket* TheSockets[KMaxPBusSockets];</codeblock> <p>(This
array is internal to Symbian platform.) </p> <p>If, on this platform, a socket
has been designated as a MultiMediaCard stack, then the function not only
returns <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>, but also provides the media information
for that socket, by filling in the members of the <xref href="GUID-FC0F974E-9ABB-348B-9AE9-778B3A1F413A.dita"><apiname>SMediaDeviceInfo</apiname></xref> object
passed in. </p> <p id="GUID-829E686F-58F9-56A9-9EC4-CD59B14E127B"><b>NewSocket()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-90615A9A-BFC2-3E1B-B2AC-7D1CF322FC65"><apiname>TMMCardControllerInterface::NewSocket()</apiname></xref> </p> <p>Implement
this function to create, and return a pointer to, an instance of the <xref href="GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7.dita"><apiname>DMMCSocket</apiname></xref> class.
This can be a class derived from <codeph>DMMCSocket</codeph>, but this should
rarely be necessary. </p> <p>The function is called from <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>. </p> <p>If
you create a <xref href="GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7.dita"><apiname>DMMCSocket</apiname></xref> object, simply forward the peripheral
bus socket number and pointer to the password store; there is no need to do
anything with them. </p> <p>If you create an instance of a <xref href="GUID-45B97680-1756-3559-8A2D-2F2E851AD6A7.dita"><apiname>DMMCSocket</apiname></xref> derived
class, then just pass the socket number and pointer to the <codeph>DMMCSocket</codeph> constructor
in your constructor's ctor list. </p> <p>Note: </p> <ul>
<li id="GUID-FA8D57D9-0827-5090-A12B-A47C936B6F70"><p>The socket number can
fall into the range 0 to <xref href="GUID-2C5A5F8F-381C-3B99-AADE-44474E629CC4.dita"><apiname>KMaxPBusSockets</apiname></xref>, and is a value
for which <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref> returned <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>. </p> </li>
<li id="GUID-3C4FCA1F-558D-5964-91F5-98588694DA70"><p>This function is only
called for sockets that are associated with MultiMediaCard devices as reported
by the function <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref>. </p> </li>
</ul> <p id="GUID-E0F612EB-85BC-533D-A71C-3FC93D9CC708"><b>NewStack()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-E2F99378-DD63-3BE0-8550-66EBF2C5D087"><apiname>TMMCardControllerInterface::NewStack()</apiname></xref> </p> <p>Implement
this function to create, and return a pointer to, an instance of a <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-4C6CA873-A798-5C79-8838-0CC3C9E914FB">DMMCStack derived class</xref>. </p> <p>The function is called from <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>. </p> <p>The
peripheral bus socket number and pointer to the socket object should be forwarded
to the <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita"><apiname>DMMCStack</apiname></xref> constructor in your class constructor's
ctor list. </p> <p>Note: </p> <ul>
<li id="GUID-CE363D03-6FEA-5AFE-A085-98D0FBAA9D52"><p>The socket number can
fall into the range 0 to <xref href="GUID-2C5A5F8F-381C-3B99-AADE-44474E629CC4.dita"><apiname>KMaxPBusSockets</apiname></xref>, and is a value
for which <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref> returned <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>. </p> </li>
<li id="GUID-7F8F2267-E8C3-5AC5-92AB-7D3179BA6D10"><p>The socket is the object
created by <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-829E686F-58F9-56A9-9EC4-CD59B14E127B">NewSocket()</xref>. </p> </li>
<li id="GUID-DF7C2369-D225-54E4-B6F1-D444343E7084"><p>This function is only
called for sockets that are associated with MultiMediaCard devices as reported
by the function <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref>. </p> </li>
</ul> <p id="GUID-33A9C3DE-80EF-5895-BC7D-EA2ED6EB083B"><b>MediaChangeID()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-10B49F15-8ED5-3CA9-873A-788B87078367"><apiname>TMMCardControllerInterface::MediaChangeID()</apiname></xref> </p> <p>Implement this function to report which media change object is to be
associated with the specified peripheral bus socket number. </p> <p>The function
is called from <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>. </p> <p>The
media change object is represented by a number, which is simply an index value
that ranges from 0 to <xref href="GUID-92555AA1-73A5-3F88-8227-8D20C977F046.dita"><apiname>KMaxMediaChanges</apiname></xref>. Internally, Symbian
platform reserves space for an array of pointers to <xref href="GUID-C122D579-BB08-3084-A30E-DC857D6E7282.dita"><apiname>DMediaChangeBase</apiname></xref> objects,
and this function allows the platform specific layer to identify which slot
is to be used for the <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita"><apiname>DMMCMediaChange</apiname></xref> object that will
correspond to the specified socket number. </p> <codeblock id="GUID-08AE1956-86E0-544A-A95C-0D16DE6694D3" xml:space="preserve">GLDEF_D DMediaChangeBase* TheMediaChanges[KMaxMediaChanges];</codeblock> <p>(This array is internal to Symbian platform.) </p> <p>Note: </p> <ul>
<li id="GUID-1A4ED330-90E5-5215-8149-093987DD5D9B"><p>The socket number can
fall into the range 0 to <xref href="GUID-2C5A5F8F-381C-3B99-AADE-44474E629CC4.dita"><apiname>KMaxPBusSockets</apiname></xref>, and is a value
for which <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref> returned <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>. </p> </li>
<li id="GUID-5EA3662D-82B2-529B-8DF4-2EAA9429990A"><p>This function is only
called for sockets that are associated with MultiMediaCard devices as reported
by the function <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref>. </p> </li>
</ul> <p id="GUID-6B1FE81F-1497-5447-9286-B0BE54AE6831"><b>NewMediaChange()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-2961273F-0D5A-3B9E-94D8-1FE216A57985"><apiname>TMMCardControllerInterface::NewMediaChange()</apiname></xref> </p> <p>Implement this function to create, and return a pointer to, an instance
of a <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-C80E57B1-933B-55D7-949B-E68DB9B96B94">DMMCMediaChange
derived class</xref>. </p> <p>The function is called from <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>. </p> <p>The
media change number should be forwarded to the <xref href="GUID-2F974AD8-551B-35F0-B72C-99122913714D.dita"><apiname>DMMCMediaChange</apiname></xref> constructor
in your class constructor's ctor list. </p> <p>Note: </p> <ul>
<li id="GUID-69B6384E-1B3C-567B-89AD-E0BE42E1F043"><p>The media change number
can fall into the range 0 to <xref href="GUID-92555AA1-73A5-3F88-8227-8D20C977F046.dita"><apiname>KMaxMediaChanges</apiname></xref>, and is the
value returned by <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-33A9C3DE-80EF-5895-BC7D-EA2ED6EB083B">MediaChangeID()</xref>. </p> </li>
<li id="GUID-FD2DA86D-5D0E-5661-AC09-55F10087D7A2"><p>This function is only
called for sockets that are associated with MultiMediaCard devices as reported
by the function <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref>. </p> </li>
</ul> <p id="GUID-E969F613-01A3-54A7-8CC6-67F4A8E9558F"><b>VccID()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-1553B339-4171-396B-89E6-6C47C539D21F"><apiname>TMMCardControllerInterface::VccID()</apiname></xref> </p> <p>Implement
this function to report which power supply unit (PSU) object is to be associated
with the specified peripheral bus socket number. </p> <p>The function is called
from <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>. </p> <p>The
PSU object is represented by a number, which is simply an index value that
ranges from 0 to <xref href="GUID-E5DEB888-EC0E-3160-BA7D-76954B282D43.dita"><apiname>KMaxPBusVccs</apiname></xref>. Internally, Symbian platform
reserves space for an array of pointers to <xref href="GUID-A8B5FB5A-4709-3F29-B2CB-81FC5B0E7D63.dita"><apiname>DPBusPsuBase</apiname></xref> objects,
and this function allows the platform specific layer to identify which slot
is to be used for the <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita"><apiname>DMMCPsu</apiname></xref> object that will correspond
to the specified socket number. </p> <codeblock id="GUID-99CD9798-2CFB-533D-82E0-352B84FA5AC9" xml:space="preserve">GLDEF_D DPBusPsuBase* TheVccs[KMaxPBusVccs];
</codeblock> <p>(This array is internal to Symbian platform.) </p> <p>Note: </p> <ul>
<li id="GUID-2C77F138-1444-5815-AB12-16D3ED6D908E"><p>The socket number can
fall into the range 0 to <xref href="GUID-2C5A5F8F-381C-3B99-AADE-44474E629CC4.dita"><apiname>KMaxPBusSockets</apiname></xref>, and is a value
for which <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref> returned <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>. </p> </li>
<li id="GUID-F8F4E84D-C46D-5547-AD19-61FB30E2CC3F"><p>This function is only
called for sockets that are associated with MultiMediaCard devices as reported
by the function <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref>. </p> </li>
</ul> <p id="GUID-083F38DB-AC65-5257-B169-2099194D3082"><b>NewVcc()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-600A5477-E99A-39BC-9982-D54C07A528BE"><apiname>TMMCardControllerInterface::NewVcc()</apiname></xref> </p> <p>The
function should create, and return a pointer to, an instance of a <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-3A1E907E-A74D-59CB-A1D6-FEF4849EF2D5">DMMCPsu derived class</xref>. </p> <p>The function is called from <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>. </p> <p>The
Power Supply Unit (PSU) number and the media change number should be forwarded
to the <xref href="GUID-FBCEFDB6-28FF-3201-8E13-F12E3759E36B.dita"><apiname>DMMCPsu</apiname></xref> constructor in your class constructor's
ctor list. </p> <p>Note: </p> <ul>
<li id="GUID-833A0119-6A98-5F5F-BAEE-5070C7C23A55"><p>The PSU number can fall
into the range 0 to <xref href="GUID-E5DEB888-EC0E-3160-BA7D-76954B282D43.dita"><apiname>KMaxPBusVccs</apiname></xref>, and is the value returned
by <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-E969F613-01A3-54A7-8CC6-67F4A8E9558F">VccID()</xref>. </p> </li>
<li id="GUID-25D7430A-2C12-50CF-BF84-FD2309732FC8"><p>The media change number
can fall into the range 0 to <xref href="GUID-92555AA1-73A5-3F88-8227-8D20C977F046.dita"><apiname>KMaxMediaChanges</apiname></xref>, and is the
value returned by <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-33A9C3DE-80EF-5895-BC7D-EA2ED6EB083B">MediaChangeID()</xref>. </p> </li>
<li id="GUID-A8908747-E292-5D01-91E2-045DE2F341B2"><p>This function is only
called for sockets that are associated with MultiMediaCard devices as reported
by the function <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-2477BA25-2ADD-55CB-93F2-84F114221EBA">IsMMCSocket()</xref>. </p> </li>
</ul> <p id="GUID-81A8BF8E-FB8B-596D-8C9A-690CD6449C12"><b>Init()</b> </p> <p> <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita#GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A/GUID-1F0C99EC-D8A9-304A-A738-BACAB5C766A6"><apiname>TMMCardControllerInterface::Init()</apiname></xref> </p> <p>Implement
this function to perform any initialization that the platform specific layer
needs to do. </p> <p>It should return <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> to indicate
successful completion, or return one of the other system-wide error codes
to indicate initialization failure. </p> <p>Note that you should <i>not</i> do
any initialization that is specifically associated with: </p> <ul>
<li id="GUID-9D706630-C477-5163-B0B2-5745D5D04559"><p>the stack - use <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-0B55A650-E9ED-56CB-B06F-B1113ACDF282">DMMCStack::Init()</xref> for
this. </p> </li>
<li id="GUID-99B883A6-FE47-5B7F-A9D1-01CCD7954DCD"><p>the power supply unit
- use <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-6EB8EF1C-BCCB-54A1-8CBA-4E8A2A20CABE">DMMCPsu::DoCreate()</xref> for
this. </p> </li>
<li id="GUID-C7EAE4E6-DEE4-515A-83B1-E40EE8D37F32"><p>dealing with media change
events - use <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-BFC23CC1-102F-5740-A608-CF91C2BC3897">DMMCMediaChange::Create()</xref> for
this. </p> </li>
</ul> </section>
<section id="GUID-732EDE1D-452A-5A48-B5DB-1196C5F8BEBD"><title> Variant DLL
entry point code</title> <p>The platform-specific layer as implemented in
the Variant DLL is a standard kernel extension. The entry point for all standard
kernel extensions is declared by a </p> <codeblock id="GUID-8835A131-2CDC-51AC-9C59-D72BAD651EA6" xml:space="preserve">DECLARE_STANDARD_EXTENSION()</codeblock> <p>statement,
followed by the block of code that runs on entry to the DLL. </p> <p>Initialization
of the MultiMediaCard DLL is done at this point, and follows the pattern shown
below. It needs to create an instance of your <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita"><apiname>TMMCardControllerInterface</apiname></xref> derived
class, followed by a call to <codeph>Create()</codeph> on this object. This
starts a cascade of effects resulting in calls to your implementation of the <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita"><apiname>TMMCardControllerInterface</apiname></xref> functions,
which in turn result in the creation of the platform-specific layer objects
associated with the MultiMediaCard sockets, i.e. the DMMCSocket, DMMCStack,
DMMCMediaChange, and DMMCPsu objects. </p> <codeblock id="GUID-16F754D1-6161-5E05-8BEA-2A89CC80CC41" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
//
// Extension Entry Point
//
{
__KTRACE_OPT(KPBUS1,Kern::Printf("Starting MMC interface"));
TInt r=KErrNoMemory;
TVARMMCardControllerInterface* pI=new TVARMMCardControllerInterface;
if (pI)
{
r=pI->Create();
}
__KTRACE_OPT(KPBUS1,Kern::Printf("MMC: Returns %d",r));
return r;
}
</codeblock> <p>In this example, <codeph>TVARMMCardControllerInterface</codeph> is
your class derived from <xref href="GUID-B1F2C60B-E098-395F-8ED0-FF33E3EC9E4A.dita"><apiname>TMMCardControllerInterface</apiname></xref> </p> </section>
<section id="GUID-00F918D3-761B-5500-805F-AB4DEE72144E"><title>Direct memory
addressing</title> <p>To transfer data between a user side process and the
media device, the Platform Specific Layer allocates a DMA-safe buffer at initialization.
This buffer is allocated from physical memory. The memory in the user side
process is virtual and you perform an inter-process copy of data between the
user side process and the buffer allocated by the Platform Specific Layer. </p> <p>Data
transfer is faster if the MultiMediaCard controller knows that an address
passed in an I/O request is a physical address. The File caching and Demand
Paging features in the file server and kernel can pass physical addresses.
A physical address avoids the need for an inter-process copy operation. </p> <p>If
you use a mechanism like <xref href="GUID-DF2F0439-AE1A-599C-91B9-6EF2177C3C7E.dita">DMA</xref> to
transfer data, and your platform specific layer can deal with physical addresses,
you need to make changes to the platform specific layer listed below. </p> <ul>
<li id="GUID-04D498F3-F4BB-5A15-BE31-8DF6F11DB9BD"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-E50081BC-C923-5DAF-950C-9E1411916FED">Implement double buffers</xref> </p> </li>
<li id="GUID-39F10C4A-4291-579E-878B-E5BD2FB9C9D0"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-575211BC-BF66-5817-9825-EE402648D0CD">Register support for physical addresses</xref> </p> </li>
<li id="GUID-5638CD98-469C-587C-87B2-CA470D76F474"><p> <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-27FCEF7D-0AAB-599C-8405-4BD284308314">Modify the data transfer phase to handle physical memory</xref> </p> </li>
</ul> <p id="GUID-E50081BC-C923-5DAF-950C-9E1411916FED"><b>Implement double buffers</b> </p> <p>If
you enable double buffer behavior, the MultiMediaCard subsystem can perform
multiple data transfers in a single bus transaction. The double buffer implementation
performs many data transfers in a single bus transaction. The MultiMediaCard
subsystem logically splits the buffer allocated by the platform specific layer
into two segments. Data transfer to the media device is in progress from one
segment - this is the active segment. Concurrently, the media driver can prepare
data in the other segment. </p> <p>To implement double buffers, you need to
make changes to the platform specific layer. </p> <p><b>Use the command descriptor functions </b> </p> <ul>
<li id="GUID-9471B51C-CB76-537F-B958-F61466A6B8F7"><p>Use the function <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-7BDD7C93-65D3-312B-B99E-B4B07AA32B2C"><apiname>TMMCCommandDesc::BlockLength()</apiname></xref> to
get the block length of the transaction. Find all direct references in the
source code of the platform specific layer to <codeph>TMMCCommandDesc::iBlockLength</codeph>.
Replace each reference with a call to <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-7BDD7C93-65D3-312B-B99E-B4B07AA32B2C"><apiname>TMMCCommandDesc::BlockLength()</apiname></xref> </p> </li>
<li id="GUID-902FFE84-8F97-511D-B554-41283550DB16"><p>Use the function <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-65B1C01B-1C8D-373A-83DB-0CEFF17667FC"><apiname>TMMCCommandDesc::BufferLength()</apiname></xref> to
get the length of the next active segment. Find all references to <codeph>TMMCCommandDesc::iTotalLength</codeph>.
There are two areas in the code where this data member can be referenced: </p> <ul>
<li id="GUID-626ACF48-ADD0-5530-8CDB-373A3855FF81"><p>code where you test
the progress of the data transfer operation and set up the MMC command. Do
not change this code, because <codeph>TMMCCommandDesc::iTotalLength</codeph> still
represents the total amount of data to be transferred. </p> </li>
<li id="GUID-25A1A62A-9B80-5ACB-B9BB-6884B4331CD7"><p>code where you set up
the DMA controller to transfer a number of blocks of data. Replace references
to <codeph>TMMCCommandDesc::iTotalLength</codeph> with calls to <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-65B1C01B-1C8D-373A-83DB-0CEFF17667FC"><apiname>TMMCCommandDesc::BufferLength()</apiname></xref>.
This describes the size of the current segment. Note that if double buffers
are not enabled, the value returned by this function is the same as <codeph>TMMCCommandDesc::iTotalLength</codeph>. </p> </li>
</ul> </li>
<li id="GUID-860835C7-D3FD-5727-9ADA-60E080EB1669"><p>You can use the function <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-DFD121A5-0C03-31A3-AF20-6E693EDC8502"><apiname>TMMCCommandDesc::IsDoubleBuffered()</apiname></xref> to
determine if the current transaction uses double buffers. </p> </li>
</ul> <p><b>Separate the command and data phases </b> </p> <p>Without double buffer
behavior, a single MMC command is always associated with a single buffer into
which the hardware transfers data. With double buffer behavior, multiple buffers
or segments are used to transfer data within a single command. You need to
separate the command and data transfer phases. </p> <p>This code fragment
is a simplified example of a platform specific layer that sets up the command
and the data transfers in separate stages: </p> <codeblock id="GUID-D349BEBB-E983-59AA-AA7F-29928D5491F5" xml:space="preserve">
TMMCErr DExampleMMCStack::IssueMMCCommandSM()
{
enum states
{
EStBegin=0,
EStSetUpCommand,
EStWaitComplete,
EStEnd
};
TMMCCommandDesc& cmd = Command();
SMF_BEGIN
/** ...omitted for clarity */
SMF_STATE(EStSetUpCommand)
/**
* Set up the controller to issue the command. Depending on
* the command type, this will prepare DMA transfers and wait
* for a response to be received before unblocking the stack.
*/
BlockCurrentSession(KMMCBlockOnASSPFunction);
SetupCommand(cmd);
If(iDataTransfer)
SetupDataTransfer(cmd);
/**
* Wait for all events to be received
* - command sent, data transferred, response received
*/
SMF_WAITS(EStWaitComplete);
SMF_STATE(EStWaitComplete)
/**
* Command issued, data transferred and response received.
* - check for and report any errors
*
* - Note, functionality omitted for clarity – in practice this will
* check the controller status and wait for more events as appropriate.
*/
TMMCErr err = KMMCErrNone;
if(iResponseExpected)
err = ExtractResponse();
if(iDataTransfer && err == KMMCErrNone)
err = CheckDataTransferErrors();
if(err)
SMF_RETURN(err);
SMF_END
}
</codeblock> <p>If you depend on the MMC controller to signal the completion
of data transfer after all blocks have been transmitted or received, change
the DMA controller. Change the code to block the stack when DMA transfer starts,
and unblock the stack when the current DMA transfer finishes. Do this operation
while you wait for the final interrupt that signals the end of the data transfer. </p> <p>The
following code fragment shows how to set the <xref href="GUID-8A9A2DD2-C630-3651-8374-17BCF2A09AC4.dita"><apiname>KMMCBlockOnASSPFunction</apiname></xref> blocking
condition before the start of DMA transfer. After DMA transfer has finished,
unblock the stack in the DMA complete service routine, <xref href="GUID-8B538AA6-9489-309F-8756-2474310CD5DA.dita"><apiname>DmaService()</apiname></xref>. </p> <codeblock id="GUID-FC9573C5-7A01-536B-8DA4-82F6DB493849" xml:space="preserve">
void DExampleMMCStack::SetupDataTransfer(const TMMCCommandDesc& aCmd)
{
TUint8* bufPtr = reinterpret_cast<TUint8*>(aCmd.iDataMemoryP);
TUint32 bufLen = aCmd.BufferLength();
/** ...omitted for clarity */
BlockCurrentSession(KMMCBlockOnASSPFunction);
iDmaController::Start(aCmd.Direction(), bufPtr, bufLen);
}
void DExampleDmaController::DmaService()
{
/** ...omitted for clarity */
Session().iState |= KMMCSessStateDoDFC;
UnBlockCurrentSession(KMMCBlockOnASSPFunction, KErrNone);
}
</codeblock> <p><b>Implement the double buffer state machine </b> </p> <p>Update the platform
specific layer to implement the double buffer state machine. You use the function <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-32596EBB-4315-3EF7-8175-8579DE69F78B"><apiname>DMMCSession::RequestMoreData()</apiname></xref>.
The platform specific layer uses this function to tell the MMC subsystem to
prepare the next segment for data transfer. You call this function when the
hardware is busy performing a DMA transfer for the current segment. This allows
the MMC Media Driver to copy data to/from the client process ready for the
next transfer while the MMC card is transferring it’s current payload. </p> <p>This
function sets the static <codeph>KMMCBlockOnMoreData</codeph> blocking condition.
The platform specific layer must use <codeph>SMF_WAITS</codeph> (or equivalent)
to suspend the platform specific layer state machine until the media driver
has processed the current segment. When finished, the command descriptor is
populated with the details of the next segment to be transferred. The <codeph>KMMCBlockOnMoreData</codeph> block
condition set by this function can be set with the <codeph>KMMCBlockOnASSPFunction</codeph> condition.
It allows the hardware to perform useful work, (for example, transfer the
current buffer to or from the card) while the media driver is busy preparing
the next buffer. In this case, the platform specific layer is unblocked when
both the hardware and media driver have completed their tasks. </p> <p>The
following code fragment shows how you do this: </p> <codeblock id="GUID-97151CF9-2C59-57D3-8856-8BCAB9BDC5B9" xml:space="preserve">TMMCErr DExampleMMCStack::IssueMMCCommandSM()
{
enum states
{
EStBegin=0,
EStSetUpCommand,
EStWaitDataTransfer
EStWaitComplete,
EStEnd
};
TMMCCommandDesc& cmd = Command();
SMF_BEGIN
/** ...omitted for clarity */
SMF_STATE(EStSetUpCommand)
/**
* Set up the controller to issue the command. Depending on
* the command type, this will prepare DMA transfers and wait
* for a response to be received before unblocking the stack.
*/
BlockCurrentSession(KMMCBlockOnASSPFunction);
SetupCommand(cmd);
If(iDataTransfer)
{
/**
* Kick off DMA transfer for the first buffer.
* …the stack will be blocked on KMMCBlockOnASSPFunction until DMA complete
*/
SetupDataTransfer(cmd);
/**
* DMA is now active. Now request the Media Driver to prepare the next
* buffer in parallel. While active, the stack will be blocked with
* the KMMCBlockOnMoreData blocking condition and unblocked when complete.
*/
Session().RequestMoreData();
}
/**
* Wait for DMA and Media Driver completion.
*/
SMF_WAITS(EStWaitDataTransfer);
SMF_STATE(EStWaitDataTransfer)
/**
* DMA is complete and the Media Driver has prepared the next buffer.
* - Start the next DMA transfer and request more data from the media driver.
*/
if(cmd.BufferLength() > 0)
{
/**
* There is more data to transfer.
* ..start DMA transfer, prepare the next buffer and wait for completion.
*/
SetupDataTransfer(cmd);
Session().RequestMoreData();
SMF_WAITS(EStWaitDataTransfer);
}
/**
* There is no more data to transfer.
* ..do whatever we need to do to wait for hardware completion
*/
// …omitted for clarity
SMF_WAITS(EStWaitComplete);
SMF_STATE(EStWaitComplete)
/**
* Command issued, data transferred and response received.
* - check for and report any errors
*
* - Note, functionality omitted for clarity – in practice this will
* check the controller status and wait for more events as appropriate.
*/
TMMCErr err = KMMCErrNone;
if(iResponseExpected)
err = ExtractResponse();
if(iDataTransfer && err == KMMCErrNone)
err = CheckDataTransferErrors();
if(err)
SMF_RETURN(err);
SMF_END
}
</codeblock> <p><b>Register support for double buffers with the platform independent layer </b> </p> <p>You
must tell the <xref href="GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B.dita#GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B/GUID-119E4B4A-03DB-5C79-AA97-14434E4BC2CA">platform
independent layer</xref> that you support double buffers. Set <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita#GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8/GUID-B11D1DA9-89C2-37E3-A2CD-19EF5706ACB8"><apiname>TMMCMachineInfo::ESupportsDoubleBuffering</apiname></xref> into
the <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita"><apiname>TMMCMachineInfo</apiname></xref> object that you pass to <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-CEF0EDF7-4B33-5452-8635-51C5319F78AE">DMMCStack::MachineInfo()</xref>. </p> <p><b>Choose the size of the buffer </b> </p> <p>To choose the optimum size
of buffer, you must perform benchmark tests on your system. A small buffer
gives you a lower command setup latency, but DMA transfers and calls to the
callback function <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-32596EBB-4315-3EF7-8175-8579DE69F78B"><apiname>DMMCSession::RequestMoreData()</apiname></xref> occur
more frequently. The time taken to set up the DMA transfers can exceed the
time taken to transfer the data into or out of the active segment. </p> <p><b>Testing </b> </p> <p>You need to do the standard E32 and F32 automated
tests to check the operation of the MMC subsystem. You also need to perform
the MMC specific manual test, T_MMCDRV. The test listed below performs data
transfers in excess of the PSL buffer size to make sure that double buffer
behavior is exercised. </p> <codeblock id="GUID-ED1D5B35-432C-5C54-9A13-92DD499316FD" xml:space="preserve">
/**
@SYMTestCaseID PBASE-T_MMCDRV-0558
@SYMTestCaseDesc Test Long Read/Write Boundaries
@SYMTestPriority High
@SYMTestActions
Perform and Write/Read/Verify for the given length (L) of data across the following boundaries.
Depending on the length, this will also perform a partial write/read at the end sector.
--------------
| Start | End |
|--------------|
| 0 | L |
| 507 | L-507 |
| 10 | L |
| 0 | L-3 |
| 27 | L-512 |
| 0 | L-509 |
| 3 | L-3 |
--------------
For each combination, the write/read/verify operations are performed in the following sequence:
a: Write and Read in single 512-byte blocks.
b: Write in a single operation (multiple blocks), Read in 512-Byte blocks.
c: Write in 512-Byte blocks, Read in a single operation (multiple-blocks).
d: Write and Read in a single operation (multiple-blocks).
In the cases where a partial read/write operation occurs (ie - the start and/or end position
don't lie within a sector boundary), the original contents of the start and/or end sectors are
read and stored at the start of the test, and compared with the contents of the sectors at the
end of the test to ensure that unwritten data within the sectors remain unaffected.
@SYMTestExpectedResults All tests must pass
@SYMPREQ1389 REQ6951 Double Buffering and SD Switch
*
*/
</codeblock> <p>The test T_MMCDRV must be performed on versions of the platform
specific layer that has: double buffers enabled, double buffers disabled,
and with a number of different buffer sizes (for example, from 32k to 256k). </p> <p>The
test cannot dynamically set the size of the buffer. You must do manual configuration
of the buffer to test all configurations. </p> <p>To measure performance,
use T_FSYSBM, with and without double buffers enable. </p> <p id="GUID-575211BC-BF66-5817-9825-EE402648D0CD"><b>Register support for physical
addresses</b> </p> <p>There are three items to do: </p> <ul>
<li id="GUID-0E169605-00B8-53F9-AF7A-5410EEE73A70"><p>you must tell the <xref href="GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B.dita#GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B/GUID-119E4B4A-03DB-5C79-AA97-14434E4BC2CA">platform
independent layer</xref> that you support physical addresses in your implementation
of <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-CEF0EDF7-4B33-5452-8635-51C5319F78AE">DMMCStack::MachineInfo()</xref>.
The function takes a <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita"><apiname>TMMCMachineInfo</apiname></xref> type. Set the <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-CB8D99BA-8EC2-3A98-B3BF-BA5FEE3A6AE1"><apiname>THardwareConfig::ESupportsDMA</apiname></xref> flags
into the <codeph>iFlags</codeph> member of <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita"><apiname>TMMCMachineInfo</apiname></xref>. </p> <p>If
you set the <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-CB8D99BA-8EC2-3A98-B3BF-BA5FEE3A6AE1"><apiname>THardwareConfig::ESupportsDMA</apiname></xref> flag, you also
set the <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-3276FBA3-7028-30C2-A820-CEBD77DCF817"><apiname>THardwareConfig::ESupportsDoubleBuffering</apiname></xref> flag
automatically. This flag enables double buffer support. You must also<xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-E50081BC-C923-5DAF-950C-9E1411916FED">implement
double buffers</xref> if you use physical addresses. </p> </li>
<li id="GUID-752318C6-301B-51B0-A064-64EAEBCF0E35"><p>You must tell the <xref href="GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B.dita#GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B/GUID-119E4B4A-03DB-5C79-AA97-14434E4BC2CA">platform
independent layer</xref> the maximum transfer length that you support. This
can be a limit imposed on you by the hardware. For example, if you use DMA,
the DMA controller can impose a limit. You set one of the flags listed below
into the <codeph>iFlags</codeph> member of <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita"><apiname>TMMCMachineInfo</apiname></xref> in
your implementation of <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-CEF0EDF7-4B33-5452-8635-51C5319F78AE">DMMCStack::MachineInfo()</xref>. </p> <p>Each flag represents a maximum transfer length. The MultiMediaCard
subsystem splits a data transfer request that is bigger than the maximum into
multiple data transfers. </p> <ul>
<li id="GUID-1BD38D21-6B02-5610-8495-4C7C194657CF"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-3375EE8E-49B8-3F24-BF40-D780AD8E1B0A"><apiname>THardwareConfig::EMaxTransferLength_256K</apiname></xref> </p> </li>
<li id="GUID-D4AB6165-036A-5259-922A-E9E1CB5749C8"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-F3BEFC8A-55F6-3B28-B383-6B33BAD2B5F7"><apiname>THardwareConfig::EMaxTransferLength_512K</apiname></xref> </p> </li>
<li id="GUID-72380863-E20E-5478-98D8-FA342C14E80C"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-20FB2892-190F-31C4-9F58-66AAB02DC4E1"><apiname>THardwareConfig::EMaxTransferLength_1M</apiname></xref> </p> </li>
<li id="GUID-68C4292C-5D9D-5E23-8608-DFBA2846A8FA"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-45913568-5C4E-3A6F-A727-8734C303AC3D"><apiname>THardwareConfig::EMaxTransferLength_2M</apiname></xref> </p> </li>
<li id="GUID-D637F68D-4530-5BE5-9B99-A7437E7AF9BC"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-66707CB4-A8E0-305E-9599-D22CBBC41E91"><apiname>THardwareConfig::EMaxTransferLength_4M</apiname></xref> </p> </li>
<li id="GUID-69AD58F1-06F6-564C-B130-BDBF8F1745BB"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-DA25B30F-671C-3B54-B58D-9F58B17BC11F"><apiname>THardwareConfig::EMaxTransferLength_8M,</apiname></xref> </p> </li>
<li id="GUID-AAE1868C-8C51-58DE-8F29-34463E0F7104"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-565830C3-14D4-3AA7-990E-78A199275DDF"><apiname>THardwareConfig::EMaxTransferLength_16M</apiname></xref> </p> </li>
<li id="GUID-BFC9B360-8023-5AC5-A2FC-F52A7D6BFD06"><p> <xref href="GUID-FA278485-D2CC-35D8-A779-8F0BDB691C3F.dita"><apiname>TMMCMachineInfoV4.iFlags</apiname></xref> </p> </li>
</ul> </li>
<li id="GUID-54BCDD97-4E54-52D5-9526-BFAC5041F8F8"><p>You must tell the <xref href="GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B.dita#GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B/GUID-119E4B4A-03DB-5C79-AA97-14434E4BC2CA">platform
independent layer</xref> the address scheme that the hardware uses. Mis-alignment
of memory can corrupt data. You set <i>one</i> of the flags shown in the list
below into the <codeph>iFlags</codeph> member of <xref href="GUID-3F9D89E8-44F0-35B3-9404-6CCAC79763E8.dita"><apiname>TMMCMachineInfo</apiname></xref> in
your implementation of <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-CEF0EDF7-4B33-5452-8635-51C5319F78AE">DMMCStack::MachineInfo()</xref>. Each flags represents a different address scheme. You can set only one
flag. If you set more than one of these flags, the creation of the media driver
fails. </p> <ul>
<li id="GUID-3055EE71-56B8-566A-A2B8-6F415F2D1675"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-A36BA08C-2010-3002-8FB2-A8E917700604"><apiname>THardwareConfig::EDma8BitAddressing</apiname></xref> </p> </li>
<li id="GUID-C71091D1-7E53-530B-8AE6-37BD9125B8B2"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-DA9AE183-855B-31A0-BDE3-54BFE894C1F8"><apiname>THardwareConfig::EDma16BitAddressing</apiname></xref> </p> </li>
<li id="GUID-6402A30F-4A49-528B-BF74-EB715521773B"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-6D844C49-AD50-3C73-BEA8-473A44B9E9D4"><apiname>THardwareConfig::EDma32BitAddressing</apiname></xref> </p> </li>
<li id="GUID-F10F9E09-151D-5BB2-B1B6-B0B08B49B8F6"><p> <xref href="GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6.dita#GUID-9E833DE8-E795-3EC8-B27B-CFB6D7E1C4C6/GUID-6F43817F-611B-326C-8A1C-55703FFC6500"><apiname>THardwareConfig::EDma64BitAddressing</apiname></xref> </p> </li>
</ul> </li>
</ul> <p>The following code is an example implementation of <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-3E5532A5-4645-3F77-A7A9-7AFF334FA5A4"><apiname>DMMCStack::MachineInfo()</apiname></xref>. </p> <codeblock id="GUID-BF942E07-A7E8-5300-9015-3FC06CAB835E" xml:space="preserve">void DVariantMmcHwStack::MachineInfo(TMMCMachineInfoV4& aMachineInfo)
/**
* Gets the machine info for the hardware variant
*
* @param aMachineInfo Info structure to populate
*/
{
aMachineInfo.iTotalSockets=MMC_DRIVECOUNT;
aMachineInfo.iTotalMediaChanges=0; // Not used at present
aMachineInfo.iTotalPrimarySupplies=0; // Not used at present
aMachineInfo.iBaseBusNumber=0;
aMachineInfo.iVersion = TMMCMachineInfoV4::EVersion4;
aMachineInfo.iMaxBusWidth = EBusWidth4;
// Report support for Physical Addressing
aMachineInfo.iFlags = TMMCMachineInfo::ESupportsDMA;
aMachineInfo.iFlags |= TMMCMachineInfo::EMaxTransferLength_1M;
aMachineInfo.iFlags |= TMMCMachineInfo::EDma16BitAddressing;
// High voltage (3.6V) power class. Set to maximum = 2000mA RMS
aMachineInfo.iHighVoltagePowerClass = TMMCMachineInfoV4::EHi200mA;
// Low voltage (1.95V) power class. Set to maximum = 200mA RMS
aMachineInfo.iLowVoltagePowerClass = TMMCMachineInfoV4::ELo200mA;
// 52 Mhz clock supported
aMachineInfo.iMaxClockSpeedInMhz = TMMCMachineInfoV4::EClockSpeed52Mhz;
}</codeblock> <p id="GUID-27FCEF7D-0AAB-599C-8405-4BD284308314"><b>Modify the data transfer
phase to handle physical memory </b> </p> <p>The implementation of double
buffers has separated the command setup and the data transfer phases. You
need to change the data transfer phase to handle physical memory. </p> <ul>
<li id="GUID-59E7DD5F-39B6-5CA5-9C8C-CC4847A885DC"><p>The data member <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-596E150B-E5F1-3945-9C00-64B8EB24550C"><apiname>TMMCCommandDesc::iDataMemoryP</apiname></xref> contains
the source or target memory address for the current data transfer command.
Use the function <xref href="GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A.dita#GUID-6B3DDBFD-3A4A-3694-A058-7794700FEC7A/GUID-3A25BD15-A832-3C76-AB68-0B4470710C3A"><apiname>TMMCCommandDesc::IsPhysicalAddress()</apiname></xref> to
determine if this address is a physical address or a virtual address. If you
do not <xref href="GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B.dita#GUID-E55B4FE5-517C-5A23-8ACA-E28EE202330B/GUID-575211BC-BF66-5817-9825-EE402648D0CD">register
support for physical addresses</xref>, this function always returns <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref>. </p> </li>
<li id="GUID-B9D101C4-FDD1-5233-9DCB-12DDA47073FC"><p>You do not need to perform
virtual address to physical address translation on physical addresses. </p> </li>
<li id="GUID-2382A7A0-B0EB-5E1F-9ADE-47389FABABBA"><p>you do not need to perform
DMA synchronization for physical addresses, because the local media subsystem
performs DMA synchronization for you. You need to perform DMA synchronization
for virtual addresses. DMA synchronization is performed by calls to <xref href="GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F.dita#GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F/GUID-3FF3C567-C1BD-3D4E-97E1-B036456A374E"><apiname>Cache::SyncMemoryBeforeDmaRead()</apiname></xref> or <xref href="GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F.dita#GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F/GUID-5F08DEAA-1237-32DE-AE41-CE7B18230972"><apiname>Cache::SyncMemoryBeforeDmaWrite()</apiname></xref>. </p> </li>
</ul> <p>The following code is an example of the changes needed for a read
operation. </p> <codeblock id="GUID-B92D3E0B-09F3-54C9-83AE-34DA544C0055" xml:space="preserve">TInt DMMCDmaRx::Start(const TMMCCommandDesc& aCmd)
/**
* Queues a DMA request after checking the buffer alignment constraints.
*
* @param aCmd The command structure containing the details about the command.
*/
{
…
TUint flags = KDmaMemDest;
// Check if a physical address has been provided with this request
if(aCmd.IsPhysicalAddress())
{
// …if so, set the appropriate flag for this DDmaRequest
flags |= KDmaPhysAddrDest;
}
TInt retval = iRequest->Fragment( KMMC_Buf_Dt_Reg,
(TUint32)aCmd.iDataMemoryP,
aCmd.BufferLength(),
flags,
0 /* no HW Flags*/);
if(retval != KErrNone)
Kern::Fault("MMC DMA RX Start Fragment", retval);
…
return KErrNone;
}
</codeblock> <codeblock id="GUID-AB1E5042-8680-57C4-87F7-71F362232C37" xml:space="preserve">void DMMCRxDmaHelp::ChannelTransfer(const SDmaPseudoDes& aDes)
{
…
TPhysAddr dest;
// Don’t perform Linear to Physical translation if we
// have already been supplied with a Physical Address
if (aDes.iFlags & KDmaPhysAddrDest)
dest = (TPhysAddr) aDes.iDest;
else
dest = Epoc::LinearToPhysical(aDes.iDest);
TPlatDma::SetDMARegister(KHoDMA_CDSA(iChno), dest);
…
}
</codeblock> </section>
</conbody></concept>