<?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-28844FE0-AE0F-531C-826E-CDA8400A0581" xml:lang="en"><title>Sessions
and Request Management</title><shortdesc>Describes how the MultiMediaCard Controller manages the sessions
and sets the order of requests. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>When a number of drivers have a session with the MultiMediaCard Controller,
the MultiMediaCard Controller can have many requests to service. </p>
<section id="GUID-9A51615A-4C00-572F-9AF4-1ED9CBC358F3"><title>Session queues</title> <p>To
handle sessions, the MultiMediaCard controller implements a scheduler. The
MultiMediaCard stack has three internal queues: </p> <ul>
<li id="GUID-0EB9FF38-2B49-5897-B663-352CEDAD8EF8"><p>an entry queue - this
is the queue onto which a session is initially added when a client submits
the session object by calling <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-8DA6B49E-FED0-3E83-8D2F-EA7B61C28015"><apiname>DMMCSession::Engage()</apiname></xref> on
it. This is anchored in the <codeph>DMMCStack::iEntryQueue</codeph> private
member. </p> </li>
<li id="GUID-21EF4132-1FA5-5FB2-9E9E-543DCD8AC8F7"><p>a ready queue - this
is the queue into which a session is moved when it is ready to be handled;
the scheduler moves all the sessions from the entry queue into the ready queue
when it can. This is anchored in the <codeph>DMMCStack::iReadyQueue</codeph> private
member. </p> </li>
<li id="GUID-5C903A7D-0540-5F09-9F41-147A98A5B4B9"><p>a working set queue
- this is the queue of sessions to be processed as chosen by the scheduler.
This queue is limited to eight sessions. The scheduler moves a session from
the ready queue to the working set queue if all current sessions in the working
set queue are blocked and there are less than eight sessions in it. This is
anchored in the <codeph>DMMCStack::iWorkSet</codeph> private member. </p> </li>
</ul> <p>All three queues are circular queues as implemented using the internal
Symbian OS class <codeph>TMMCSessionRing</codeph>. </p> <fig id="GUID-E8B1FA7F-1759-52BC-A9D8-80FF7E39FE51">
<image href="GUID-B30D6027-EB0F-578F-9B2F-AFC2DFD27E39_d0e383478_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-FF74AAF0-D1F6-59A7-A859-B73DF946C92F"><title>The scheduler</title> <p>Every
time one of the following events occurs, the MultiMediaCard stack invokes
its scheduler to deal with that event: </p> <ul>
<li id="GUID-06C336CB-581E-59A3-96BA-D9C4BD43154E"><p>a client submitting
a session to the MultiMediaCard controller </p> </li>
<li id="GUID-FFA95B03-F68F-5B1A-8A36-2D8F0D490AD1"><p>a client aborting a
session </p> </li>
<li id="GUID-00D34161-C53E-5BED-9818-F0CCEED8FDF4"><p>a card interrupt occurring. </p> </li>
</ul> <p>The stack invokes the scheduler by calling the internal function <codeph>DMMCStack::Scheduler()</codeph>. </p> </section>
<section id="GUID-25D6F073-7310-4654-BC69-4B032EFB13A5"><title>Blocking a session</title><p>Sometimes, the MultiMediaCard
controller has to perform its processing in a DFC context. In those cases
the Controller postpones operation by queuing a DFC; the DFC call-back function
then resumes the operation by invoking the scheduler again. This means that
the scheduler may be running as part of a kernel executive call, a DFC or
an interrupt service routine. </p> <p>In general, the MultiMediaCard controller
processes a session in stages, issuing commands, checking responses, reading
or writing data etc. Each stage is usually done asynchronously, first setting
up the activity and then setting up a means of being notified when that activity
is complete, for whatever reason (e.g. issuing a command and setting up an
interrupt when a response has been received). </p> <p>If a session is waiting
on an asynchronous operation, it is blocked. When one session is blocked,
the stack tries to process another session which isn’t blocked. </p> <p>The
blocking of sessions is set up and implemented internally to Symbian OS. However,
the platform specific layer can block a session by calling the <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-E7B38752-F9AB-3A66-8FB6-E321717A63B5"><apiname>DMMCStack::BlockCurrentSession()</apiname></xref> function
with the <xref href="GUID-8A9A2DD2-C630-3651-8374-17BCF2A09AC4.dita"><apiname>KMMCBlockOnASSPFunction</apiname></xref> bit set in the parameter
passed to that function. </p> <p>Internally, the <codeph>DMMCSession::iBlockOn</codeph> private
data member is set when a session is blocked. This is a bit-mask variable
containing the reason that the session is blocked. </p></section>
<section id="GUID-4EE6ABBA-9863-499C-BB5F-96BB0782042E"><title>Scheduler algorithm</title><p>The following flow-diagram shows
the algorithm used by the scheduler. </p> <fig id="GUID-78F3CD78-61F3-5DD8-8D0D-9D5251D11158">
<image href="GUID-AA53650C-664C-53F0-8BE9-445677FC1FE2_d0e383551_href.png" placement="inline"/>
</fig> <p>The <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita"><apiname>DMMCStack</apiname></xref> private members referenced in this
diagram have the following meaning: </p> <table id="GUID-E1F971E8-949B-527B-B0EC-8D21BBB0EDE0">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>DMMCStack::iAbortReq</codeph> </p> </entry>
<entry><p>Set to <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> when there are sessions on the stack
that have been marked for abort by the client. This is set as a result of
a call to <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-84B74DDE-4D86-3D25-BDC6-CEF580E8C0FB"><apiname>DMMCSession::Abort()</apiname></xref>. </p> </entry>
</row>
<row>
<entry><p> <codeph>DMMCStack::iAttention</codeph> </p> </entry>
<entry><p>Set to <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> when there are sessions ready to
run. This is set when a session is submitted to the stack as a result of a
call to <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-8DA6B49E-FED0-3E83-8D2F-EA7B61C28015"><apiname>DMMCSession::Engage()</apiname></xref>, or when a session becomes
unblocked. </p> </entry>
</row>
<row>
<entry><p> <codeph>DMMCStack::iCompReq</codeph> </p> </entry>
<entry><p>Set to <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> when there are sessions on the stack
ready to complete. This is set internally by the controller through calls
to the private functions <codeph>DMMCStack::MarkComplete()</codeph> or <codeph>DMMCStack::CompleteAll()</codeph>. </p> </entry>
</row>
<row>
<entry><p> <codeph>DMMCStack::iInitialise</codeph> </p> </entry>
<entry><p>Set to <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> when stack initialization (CIM_INIT_STACK)
has been forced. This is set when the controller needs to re-power the stack,
and to power up a card on client requests. </p> </entry>
</row>
</tbody>
</tgroup>
</table></section>
</conbody></concept>