<?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-80E0DB93-A96A-54A8-A201-E11935418BE7" xml:lang="en"><title>State

Machines</title><shortdesc>Description of the structure and operation of state machines.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The MultiMediaCard Controller uses state machines to manage the interactions

with the MultiMediaCard hardware. </p>

<p>State machines allows the controller to maintain the state of each submitted

session – allowing it to schedule a second session when the first becomes

blocked, for example. </p>

<p>To handle the complex sequence of bus operations involved, the controller

implements a state machine stack, allowing a parent state machine function

to invoke a child state machine function. The state machine stack allows nesting

of children down to a depth of 10 levels. </p>

<p>Each session object has its own individual state machine stack because

each session runs its own sequence of bus operations, with the controller

managing these multiple sequences. This means that each session object has

a state machine object, an instance of the <xref href="GUID-022AC0FE-86EE-3908-A9F8-4A33D04A68A5.dita"><apiname>TMMCStateMachine</apiname></xref> class. </p>

<fig id="GUID-3CD3F1EF-FB6A-5D5D-B806-75536F8DF533">

<image href="GUID-4592D493-A47C-5622-8C03-F24FABB4381C_d0e405416_href.png" placement="inline"/>

</fig>

<p>The state machine remembers the next state and child function name, and

moves to that state as soon as control returns to the session. </p>

<p>The stack chooses the next session to be handled and manages the state

machine through the state machine dispatcher. </p>

<ul>

<li id="GUID-76BEBC23-FC9D-5244-A3EA-2A5424FC02D7"><p> <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita#GUID-80E0DB93-A96A-54A8-A201-E11935418BE7/GUID-44473E52-82B4-55E7-AE85-15AC88CE5BEB">Structure of the state machine stack</xref> </p> </li>

<li id="GUID-0A56A8B9-65D7-54CB-A584-8C3C9AEFE339"><p> <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita#GUID-80E0DB93-A96A-54A8-A201-E11935418BE7/GUID-E8FCFD65-4664-52EE-B658-FCABF50D501D">Structure of a state machine function</xref> </p> </li>

<li id="GUID-85E36E04-60CD-5560-93DE-5C15E8DBDD45"><p> <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita#GUID-80E0DB93-A96A-54A8-A201-E11935418BE7/GUID-667C5A70-0ABB-525F-A309-58102E380400">Example of a state machine calling sequence</xref> </p> </li>

</ul>

<section id="GUID-44473E52-82B4-55E7-AE85-15AC88CE5BEB"><title>Structure of

the state machine stack</title> <p>The stack itself is represented as an array

of <xref href="GUID-DDCE8054-1656-34EF-9CBC-53C796BFD5A6.dita"><apiname>TMMCMachineStackEntry</apiname></xref> objects contained within the state

machine object <xref href="GUID-022AC0FE-86EE-3908-A9F8-4A33D04A68A5.dita"><apiname>TMMCStateMachine</apiname></xref>. </p> <p>The state machine

maintains a "pointer", <xref href="GUID-022AC0FE-86EE-3908-A9F8-4A33D04A68A5.dita#GUID-022AC0FE-86EE-3908-A9F8-4A33D04A68A5/GUID-5EC9B7D0-A3A9-35DF-A91D-65920372C9A4"><apiname>TMMCStateMachine::iSP</apiname></xref>, to the current

state entry. This is not a true pointer, but just a value that indexes into

the array. However, for all practical purposes it has the effect of a pointer.

Each state entry in the stack is thought of as having a parent-child relationship

with the other. </p> <p>Each state entry maintains three pieces of information: </p> <ul>

<li id="GUID-81454E68-4603-5211-8F9F-70F0F2F4B95D"><p>A pointer to the state

machine function. </p> </li>

<li id="GUID-B20834EB-3EAE-5D79-8564-8B2A5490A057"><p>A variable containing

the current state; the value and meaning of the state is defined by the state

machine function. </p> </li>

<li id="GUID-32AFB296-0D5F-5FF7-9ECD-C9F798E04542"><p>A bitmask of <xref href="GUID-FF4AB1CF-7A2C-3FC6-B123-D6819E1BCDCA.dita"><apiname>TMMCErr</apiname></xref> defined

error conditions; these are set by the parent state machine function so that

it gets the chance to trap those errors if the child state machine function

returns those errors. Errors are propagated up the stack, and any error conditions

not trapped at any level in the state machine hierarchy leads to the state

machine terminating with that error value. </p> </li>

</ul> <fig id="GUID-064C53DB-6A96-5C6D-B3CD-B40A0251EF66">

<image href="GUID-D8911BE6-100D-588A-8E5C-A429A72AFCDA_d0e405501_href.png" placement="inline"/>

</fig> <p>In general, the overall state of the state machine reflects the

state of the current state entry; for example, <xref href="GUID-E32D6BC3-F8D9-3F7E-94F6-56633B645D6A.dita#GUID-E32D6BC3-F8D9-3F7E-94F6-56633B645D6A/GUID-48F37107-2D11-3550-890B-D79844A97DBF"><apiname>TMMCStatemachine::State()</apiname></xref> returns

the state held in the current state entry. </p> <p>While the flow of control

through a stack can be complex, the following diagram shows a short example

snapshot. Here, the current state in the current stack entry is <codeph>Sn</codeph> and

is handled by the function <codeph>PF()</codeph>. The code decides to pass

control to the child function <codeph>CF()</codeph>, but ensures that, on

completion, the next state in the current stack entry will be <codeph>Sn+1</codeph>. </p> <fig id="GUID-6ACBC49E-14EE-526B-A1A3-426B64BF8476">

<image href="GUID-D2D41326-BA88-5A02-805B-5EAEC29ADB5D_d0e405528_href.png" placement="inline"/>

</fig> <p>For example, the <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-F71A4421-2F9E-39FD-A352-97ECAAFE822D"><apiname>DMMCStack::CIMUpdateAcqSM()</apiname></xref> function

implements the CIM_UPDATE_ACQ macro as defined by the <i>MultiMediaCard System

Specification</i>, and is a typical state machine function. </p> <p>Most commands

and macros involve one or more asynchronous operations and while such operations

are outstanding, a session is blocked. While a session is blocked, its state

machine dispatch function is not called. As soon an asynchronous event removes

the blocking condition, control returns to the state machine. </p> </section>

<section id="GUID-E8FCFD65-4664-52EE-B658-FCABF50D501D"><title>Structure of

a state machine function</title> <p>State machine functions are defined and

implemented in the <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita"><apiname>DMMCStack</apiname></xref> class in pairs: one as a static

function, and the other as a member function. The static variant takes a <codeph>TAny*</codeph> pointer

that is cast to a <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita"><apiname>DMMCStack</apiname></xref> pointer, and the <codeph>DMMCStack</codeph> member

function is then called: </p> <codeblock id="GUID-F5EEA20F-2312-5394-84C4-5E568995291A" xml:space="preserve">TMMCErr DMMCStack::FunctionNameSMST( TAny* aPtr )

    {

    return( STATIC_CAST(DMMCStack*,aPtr)->FunctionNameSM() );

    }

</codeblock> <codeblock id="GUID-3C01127E-4EBA-59AC-91F8-1F004A74E45B" xml:space="preserve">TMMCErr DMMCStack::FunctionNameSM()

    {

    enum states {EStBegin=0, EStNext,…, EStEnd };    // Enumeration of states for this state machine

    DMMCSession& s = Session();

    SMF_BEGIN

    // State EStBegin

    // Actions for state EStBegin

    SMF_STATE( EStNext )

    // State EStNext

    // Actions for state EStNext

    SMF_END

    }

</codeblock> <p>A state machine function can release control and wait to be

re-entered by returning zero. If its session is not blocked then that will

happen immediately. If the state machine function returns non-zero, the session

will be completed with that error code unless the parent state machine function

has explicitly intercepted such an error by setting the trap mask. </p> <ul>

<li id="GUID-BEE3954A-733D-55CE-B09C-4B49304B44E1"><p> <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita#GUID-80E0DB93-A96A-54A8-A201-E11935418BE7/GUID-901D8456-F8D3-5E92-B3DA-EFE556D8C48B">Important points to note</xref> </p> </li>

<li id="GUID-DA29FD1E-93EF-56C1-9650-8CE22B655897"><p> <xref href="GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita#GUID-80E0DB93-A96A-54A8-A201-E11935418BE7/GUID-DBBA1450-AE5A-50E5-9B8C-F697CEFAD590">Blocking on an asynchronous request</xref> </p> </li>

</ul> <p id="GUID-901D8456-F8D3-5E92-B3DA-EFE556D8C48B"><b>Important points to note</b> </p> <p>Each

state machine function must define a list of states that can exist. States

are defined as an enumeration whose first and last values <i>must</i> be labelled <codeph>EStBegin</codeph> and <codeph>EStEnd</codeph>,

respectively. <codeph>EStBegin</codeph> must have the value zero. Any other

intermediate states are program defined. </p> <p>To make the state machine

functions more readable, a number of macros exist to help with the layout

of the function code, and to control program flow. The most basic macros are <xref href="GUID-C095E583-3E71-31F3-B092-627357D72958.dita"><apiname>SMF_BEGIN</apiname></xref>, <xref href="GUID-38811BD9-F27C-3408-A04F-053314A2CF84.dita"><apiname>SMF_STATE</apiname></xref> and <xref href="GUID-C1089896-DD68-399C-BF34-2495C51A0CA1.dita"><apiname>SMF_END</apiname></xref> that expand into a switch statement. The above code expands

to: </p> <codeblock id="GUID-16AE9141-5BE1-5B54-B083-7F60133DD018" xml:space="preserve">TMMCErr DMMCStack::FunctionNameSM()

{

enum states {EStBegin=0, EStNext,…, EStEnd };    // Enumeration of states for this state machine

DMMCSession& s = Session();

TMMCStateMachine& m = Machine();            //SMF_BEGIN

const TMMCErr err = m.SetExitCode( 0 );        //SMF_BEGIN

for(;;)                                        //SMF_BEGIN

    {                                        //SMF_BEGIN

    switch(m.State())                        //SMF_BEGIN

        {                                    //SMF_BEGIN

        case EStBegin:                        //SMF_BEGIN

            {                                //SMF_BEGIN

            if(err) (void)0;                //SMF_BEGIN 

            // State EStBegin

            // Actions for state EStBegin

            }                                //SMF_STATE

        case EStNext:                        //SMF_STATE

            {                                //SMF_STATE

            // State EStNext

            // Actions for state EStNext

        case EStEnd:                                                //SMF_END

            break;                                                    //SMF_END

            default:                                                //SMF_END

            DMMCController::Panic(DMMCController::EMMCMachineState);//SMF_END

        }                                                            //SMF_END

        break;                                                        //SMF_END

    }                                                                //SMF_END

return(m.Pop());                                                    //SMF_END

}</codeblock> <p>Notes: </p> <ul>

<li id="GUID-7542D030-2641-5A15-A5AF-A02C491B24BB"><p>be aware that SMF_BEGIN

generates an open curly bracket while SMF_STATE generates a corresponding

close bracket, and SMF_END closes the switch statement. </p> </li>

</ul> <p>You need to be aware of the code that is generated by these macros.

In particular, some such as SMF_BEGIN generate an opening curly brace, while

others such as SMF_STATE generate a corresponding close curly brace. Also,

you need to know whether a macro generates a <codeph>break;</codeph> or a <codeph>return;</codeph> statement.

Lack of awareness here may cause code to be generated that flows from one

case statement to another, which may not be your intent. </p> <ul>

<li id="GUID-7C57CF3E-0EB9-56A4-A07A-86027F5B42BA"><p> <xref href="GUID-C095E583-3E71-31F3-B092-627357D72958.dita"><apiname>SMF_BEGIN</apiname></xref> </p> </li>

<li id="GUID-9A87EEA6-6D40-53E1-BCEE-F9A20C22D51D"><p> <xref href="GUID-C1089896-DD68-399C-BF34-2495C51A0CA1.dita"><apiname>SMF_END</apiname></xref> </p> </li>

<li id="GUID-3ADD2CCB-4C83-54EC-80DB-3C8CFDDDCB7A"><p> <xref href="GUID-2BA7F4A7-ECB0-3839-809B-4C32D4F451BA.dita"><apiname>SMF_NEXTS</apiname></xref> </p> </li>

<li id="GUID-41D972A7-18DE-5CE5-B0D6-039B0126199C"><p> <xref href="GUID-ACD776A5-5439-3BE9-8DD8-B537D8C2C637.dita"><apiname>SMF_CALL</apiname></xref> </p> </li>

<li id="GUID-87C8FC8C-F810-5B3F-A7CC-99D6515F8F04"><p> <xref href="GUID-3802119E-0FC0-3B7C-9582-21563EC9AF61.dita"><apiname>SMF_CALLWAIT</apiname></xref> </p> </li>

<li id="GUID-89669A58-5168-508A-AF9F-34C3347F0A69"><p> <xref href="GUID-2B6FA032-F8F9-3205-9CBB-EFB96691ACC9.dita"><apiname>SMF_CALLMYS</apiname></xref> </p> </li>

<li id="GUID-A6C9952A-223E-5687-B67C-D89D50070BDB"><p> <xref href="GUID-C1D65C79-F781-3E22-AA73-F75BA2516F6F.dita"><apiname>SMF_CALLMEWR</apiname></xref> </p> </li>

<li id="GUID-7FF0DFC9-D9DC-5E08-B668-4BC62B6E50EC"><p> <xref href="GUID-A143CA61-AA6B-3C5F-9E58-50BAF3786262.dita"><apiname>SMF_INVOKES</apiname></xref> </p> </li>

<li id="GUID-F02BE381-0BA2-5E9D-AFB7-9064FBADC64C"><p> <xref href="GUID-A73CAEB2-2413-371E-A56F-2757C0723514.dita"><apiname>SMF_INVOKEWAITS</apiname></xref> </p> </li>

<li id="GUID-A39E56F8-DE55-5EDE-A955-24E198026F39"><p> <xref href="GUID-94214574-2CCD-3BE4-ABD4-6A58328B29A2.dita"><apiname>SMF_WAIT</apiname></xref> </p> </li>

<li id="GUID-1CB69F09-3BAC-5C41-B20E-5A2896C0E18E"><p> <xref href="GUID-33FBF199-09B8-32C3-BAD6-92D277722DB3.dita"><apiname>SMF_WAITS</apiname></xref> </p> </li>

<li id="GUID-46D7BB96-3EC7-5207-BEE4-1E3ABB145D6B"><p> <xref href="GUID-B13D0665-AD49-348F-8795-67E8761B0BC8.dita"><apiname>SMF_RETURN</apiname></xref> </p> </li>

<li id="GUID-A9A4DB91-2648-534D-BEA3-57A23147D750"><p> <xref href="GUID-2BA73A03-7379-394C-B9E8-4525316AF91F.dita"><apiname>SMF_EXIT</apiname></xref> </p> </li>

<li id="GUID-E75E1BF0-CD8B-5EEA-98EA-13176AE0A308"><p> <xref href="GUID-57CF6330-1EA6-36A9-B2A1-2BB360B1E7FD.dita"><apiname>SMF_EXITWAIT</apiname></xref> </p> </li>

<li id="GUID-D0617F39-4CF6-5FA7-995C-50688A82E703"><p> <xref href="GUID-6E9EF7EB-A9A2-3FA1-902D-188B4930927F.dita"><apiname>SMF_JUMP</apiname></xref> </p> </li>

<li id="GUID-83791CBF-298A-5B5F-A9A0-8FB902AE81EB"><p> <xref href="GUID-85E63D6B-521B-309A-A1B1-18FDFCF626A0.dita"><apiname>SMF_JUMPWAIT</apiname></xref> </p> </li>

<li id="GUID-F657F501-47AE-57D0-BEB6-A051176FC279"><p> <xref href="GUID-BF735A08-6E69-374F-8052-EF6CA101A3C3.dita"><apiname>SMF_GOTONEXTS</apiname></xref> </p> </li>

<li id="GUID-F7D1B6D8-51A2-5C73-A709-1BB10CD27620"><p> <xref href="GUID-AA215584-34D9-36DA-A05A-8A4DF4636D5E.dita"><apiname>SMF_GOTOS</apiname></xref> </p> </li>

<li id="GUID-042539CB-3019-57A2-B0AD-F1417756F842"><p> <xref href="GUID-38811BD9-F27C-3408-A04F-053314A2CF84.dita"><apiname>SMF_STATE</apiname></xref> </p> </li>

<li id="GUID-ADD382E6-32C0-5773-8958-057F440C3FEC"><p> <xref href="GUID-11B9D102-4548-3321-8318-26E940273880.dita"><apiname>SMF_BPOINT</apiname></xref> </p> </li>

</ul> <p id="GUID-DBBA1450-AE5A-50E5-9B8C-F697CEFAD590"><b> Blocking on an asynchronous

request</b> </p> <p>The state machine can be made to block. This is done so

that you can wait for an asynchronous operation to complete. When the operation

completes, it unblocks the state machine. There are two stages to blocking

a state machine: </p> <ul>

<li id="GUID-544A1BE8-2896-5CEB-ADEB-4F63E26389C4"><p>Call <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> to

indicate that the state machine associated with the current session is to

be blocked </p> </li>

<li id="GUID-BDB03808-C220-5518-B0E7-232845FD0AD6"><p>Execute one of the SMF_xxxWAIT

macros to return from the current state machine function and wait. </p> </li>

</ul> <p>Note that the state machine function <i>must</i> return by calling

one of the SMF_xxxWAIT macros. It must not poll or sit in a loop! The state

machines are not threaded, and this means that CPU time can only be given

to other tasks if the function returns. </p> <p> <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> takes

an argument describing the type of block. The state machine will only unblock

when an unblock request with the matching argument is called. In the platform

specific layer of the MultiMediaCard controller, you should always set the <xref href="GUID-8A9A2DD2-C630-3651-8374-17BCF2A09AC4.dita"><apiname>KMMCBlockOnASSPFunction</apiname></xref> bit

in the argument passed to <codeph>BlockCurrentSession()</codeph>. </p> <p>To

unblock the state machine, call <xref href="GUID-B5193656-9819-3E00-A335-EEF1726115A5.dita#GUID-B5193656-9819-3E00-A335-EEF1726115A5/GUID-E1FEFAD3-CD02-38AF-8E45-41099192D583"><apiname>DMMCStack::UnBlockCurrentSession()</apiname></xref> setting

the <xref href="GUID-8A9A2DD2-C630-3651-8374-17BCF2A09AC4.dita"><apiname>KMMCBlockOnASSPFunction</apiname></xref> bit in the flags argument passed

to the function, and also an error code. This will invoke the state machine

scheduler, which will re-start the state machine. </p> <p>Note that further

state machine processing must take place in a DFC rather than within the interrupt

service routine (ISR), and this can be forced by ORing the session status, <xref href="GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A.dita#GUID-0186BEDE-8E28-3F8C-8CAE-A8B92F41F47A/GUID-252B39FE-C203-37AD-82A4-63E9BFFD3473"><apiname>DMMCSession::iState</apiname></xref>,

with the <xref href="GUID-5CF9ED11-2F3A-3E9B-9BFF-87DBE261F097.dita"><apiname>KMMCSessStateDoDFC</apiname></xref> bit <i>before</i> unblocking

the session. The bit has the effect of queueing a DFC to resume the state

machine at some later stage, before returning to the ISR. </p> <p>The following

code shows the idea: </p> <codeblock id="GUID-C4C8C8EA-4A16-5E9C-A64D-194D7D17403C" xml:space="preserve">TMMCErr DMMCStackAssp::DoSomethingSM()

    {

    enum states {EStBegin=0, EStDone,EStEnd };    // enumeration of states for this state machine

    SMF_BEGIN

    // start the asynchronous operation

    BlockCurrentSession( KMMCBlockOnASSPFunction );

    StartAsynchronousOp();

    // block and wait. Go to state EStDone when the asynchronous op is complete

    SMF_WAITS( EStDone );

    SMF_STATE( EStDone )

    // operation is complete, check for errors and return from state machine

    TInt errors = CheckForHardwareErrors();

    SMF_RETURN( errors );

    SMF_END

    }

</codeblock> <codeblock id="GUID-5CE18C2D-2780-5966-BC26-DD33D31BB5B3" xml:space="preserve">void TMMCInterrupt::Service( TAny* aParam )

    {

    Session().iState |= KMMCSessStateDoDFC;

    UnBlockCurrentSession(KMMCBlockOnASSPFunction, KMMCErrNone);

    }

</codeblock> </section>

<section id="GUID-667C5A70-0ABB-525F-A309-58102E380400"><title>Example of

a state machine calling sequence</title> <p>This shows the state machine calling

sequence that implements the reading of a single block on a MultiMediaCard,

where the card is not yet selected. Note that the lowest level state machine

function called is <codeph>IssueMMCCommandSM()</codeph>, which is implemented

by the base port. </p> <fig id="GUID-A67E1B8E-322A-5AC8-9EEA-AC24C8868E81">

<image href="GUID-A51C3E48-3ED0-519B-A128-C5175D7E175B_d0e405927_href.png" placement="inline"/>

</fig> </section>

</conbody></concept>