/*
 * GenSM.c
 *
 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved.      
 * All rights reserved.      
 * 
 * This program and the accompanying materials are made available under the 
 * terms of the Eclipse Public License v1.0 or BSD License which accompanies
 * this distribution. The Eclipse Public License is available at
 * http://www.eclipse.org/legal/epl-v10.html and the BSD License is as below.                                   
 *                                                                       
 * Redistribution and use in source and binary forms, with or without    
 * modification, are permitted provided that the following conditions    
 * are met:                                                              
 *                                                                       
 *  * Redistributions of source code must retain the above copyright     
 *    notice, this list of conditions and the following disclaimer.      
 *  * Redistributions in binary form must reproduce the above copyright  
 *    notice, this list of conditions and the following disclaimer in    
 *    the documentation and/or other materials provided with the         
 *    distribution.                                                      
 *  * Neither the name Texas Instruments nor the names of its            
 *    contributors may be used to endorse or promote products derived    
 *    from this software without specific prior written permission.      
 *                                                                       
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS   
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT     
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT  
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT      
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT   
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/** \file GenSM.c
 *  \brief Generic state machine implementation
 *
 *  \see GenSM.h
 */


#define __FILE_ID__  FILE_ID_128
#include "tidef.h"
#include "osApi.h"
#include "report.h"
#include "GenSM.h"

/* generic state machine object structure */
typedef struct
{
    TI_HANDLE       hOS;               /**< OS handle */ 
    TI_HANDLE       hReport;           /**< report handle */ 
    TGenSM_matrix   tMatrix;           /**< next state/action matrix */
    TI_UINT32       uStateNum;         /**< Number of states in the matrix */
    TI_UINT32       uEventNum;         /**< Number of events in the matrix */
    TI_UINT32       uCurrentState;     /**< Current state */
    TI_UINT32       uEvent;            /**< Last event sent */
    void            *pData;            /**< Last event data */
    TI_BOOL         bEventPending;     /**< Event pending indicator */
    TI_BOOL         bInAction;         /**< Evenet execution indicator */
    TI_UINT32       uModuleLogIndex;   /**< Module index to use for printouts */
    TI_INT8         *pGenSMName;       /**< state machine name */
    TI_INT8         **pStateDesc;      /**< State description strings */
    TI_INT8         **pEventDesc;      /**< Event description strings */
} TGenSM;


/** 
 * \fn     genSM_Create 
 * \brief  Cerates a generic state machine object
 * 
 * Cerates a generic state machine object. Allocates system resources.
 * 
 * \note   event/action matrix and debug descriptions are used by reference, and are not copied! 
 * \param  hOS - handle to the OS object
 * \return Handle to the generic state machine object
 * \sa     GenSM_Unload, GenSM_Init, genSM_SetDefaults
 */
TI_HANDLE genSM_Create (TI_HANDLE hOS)
{
    TGenSM      *pGenSM = NULL;

    /* Allocate object storage */
    pGenSM = os_memoryAlloc (hOS, sizeof(TGenSM),MemoryNormal);
    if (NULL != pGenSM)
    {
        /* Store OS handle */
        pGenSM->hOS = hOS;
    }

    return (TI_HANDLE)pGenSM;
}

/** 
 * \fn     genSM_Unload 
 * \brief  Unloads a generic state machine object
 * 
 * Unloads a generic state machine object. Frees system resources consumed by the object.
 * 
 * \param  hGenSM - hanlde to the generic state machine object
 * \return None
 * \sa     GenSM_Create 
 */
void genSM_Unload (TI_HANDLE hGenSM)
{
    TGenSM      *pGenSM =       (TGenSM*)hGenSM;

    /* free the generic state machine object storage */
    os_memoryFree (pGenSM->hOS, hGenSM, sizeof (TGenSM));
}

/** 
 * \fn     genSM_Init 
 * \brief  Initializes the generic state machine object
 * 
 * Initializes the generic state machine object. Store handles to other modules.
 * 
 * \param  hGenSM - hanlde to the generic state machine object
 * \param  hReport - handle to the report module
 * \return None
 * \sa     GenSM_Create, genSM_SetDefaults
 */
void genSM_Init (TI_HANDLE hGenSM, TI_HANDLE hReport)
{
    TGenSM      *pGenSM =       (TGenSM*)hGenSM;

    /* store report handle */
    pGenSM->hReport = hReport;
}

/** 
 * \fn     genSM_SetDefaults 
 * \brief  Set default values to the generic state machine 
 * 
 * Set default values to the generic state machine
 * 
 * \note   event/action matrix and debug descriptions are used by reference, and are not copied! 
 * \param  hGenSM - hanlde to the generic state machine object
 * \param  uStateNum - number of states
 * \param  uEventNum - number of events
 * \param  pMatrix - pointer to the event/actions matrix
 * \param  uInitialState - the initial state
 * \param  pGenSMName - a string describing the state machine, for debug prints
 * \param  pStateDesc - strings describing the state machine states, for debug prints
 * \param  pEventDesc - strings describing the state machine events, for debug prints
 * \param  uModuleLogIndex - Log index used by the module using the state machine
 * \return None
 * \sa     genSM_Create, genSM_Init
 */
void genSM_SetDefaults (TI_HANDLE hGenSM, TI_UINT32 uStateNum, TI_UINT32 uEventNum,
                        TGenSM_matrix pMatrix, TI_UINT32 uInitialState, TI_INT8 *pGenSMName, 
                        TI_INT8 **pStateDesc, TI_INT8 **pEventDesc, TI_UINT32 uModuleLogIndex)
{
    TGenSM      *pGenSM =       (TGenSM*)hGenSM;

    /* set values */
    pGenSM->uStateNum       = uStateNum;
    pGenSM->uEventNum       = uEventNum;
    pGenSM->tMatrix         = pMatrix;
    pGenSM->uCurrentState   = uInitialState;
    pGenSM->pGenSMName      = pGenSMName;
    pGenSM->pStateDesc      = pStateDesc;
    pGenSM->pEventDesc      = pEventDesc;
    pGenSM->uModuleLogIndex = uModuleLogIndex;
    pGenSM->bEventPending   = TI_FALSE;
    pGenSM->bInAction       = TI_FALSE;
}

void genSM_Event (TI_HANDLE hGenSM, TI_UINT32 uEvent, void *pData)
{
    TGenSM              *pGenSM =       (TGenSM*)hGenSM;
    TI_UINT32           uCurrentState;
    TGenSM_actionCell   *pCell;

#ifdef TI_DBG
    /* sanity check */
    if (uEvent >= pGenSM->uEventNum)
    {
        TRACE3(pGenSM->hReport, REPORT_SEVERITY_ERROR , ": module: %d received event %d, which is out of events boundry %d\n", pGenSM->uModuleLogIndex, uEvent, pGenSM->uEventNum);
    }
    if (TI_TRUE == pGenSM->bEventPending)
    {
        TRACE3(pGenSM->hReport, REPORT_SEVERITY_ERROR , ": module: %d received event %d, when event %d is pending execution!\n", pGenSM->uModuleLogIndex, uEvent, pGenSM->uEvent);
    }
#endif

    /* mark that an event is pending */
    pGenSM->bEventPending = TI_TRUE;

    /* save event and data */
    pGenSM->uEvent = uEvent;
    pGenSM->pData = pData;

    /* if an event is currently executing, return (new event will be handled when current event is done) */
    if (TI_TRUE == pGenSM->bInAction)
    {
        TRACE1(pGenSM->hReport, REPORT_SEVERITY_INFORMATION , ": module: %d delaying execution of event \n", pGenSM->uModuleLogIndex);
        return;
    }

    /* execute events, until none is pending */
    while (TI_TRUE == pGenSM->bEventPending)
    {
        /* get the cell pointer for the current state and event */
        pCell = &(pGenSM->tMatrix[ (pGenSM->uCurrentState * pGenSM->uEventNum) + pGenSM->uEvent ]);
        

        /* print state transition information */
		TRACE4(pGenSM->hReport, REPORT_SEVERITY_INFORMATION, "genSM_Event: module %d <currentState = %d, event = %d> --> nextState = %d\n", pGenSM->uModuleLogIndex, pGenSM->uCurrentState, uEvent, pCell->uNextState);

        /* mark that event execution is in place */
        pGenSM->bInAction = TI_TRUE;

        /* mark that pending event is being handled */
        pGenSM->bEventPending = TI_FALSE;
        
        /* keep current state */
        uCurrentState = pGenSM->uCurrentState;

        /* update current state */
        pGenSM->uCurrentState = pCell->uNextState;

        /* run transition function */
        (*(pCell->fAction)) (pGenSM->pData);

        /* mark that event execution is complete */
        pGenSM->bInAction = TI_FALSE;
    }
}

/** 
 * \fn     genSM_GetCurrentState
 * \brief  retrieves the state machine current state
 * 
 * retrieves the state machine current state
 * 
 * \param  hGenSM - hanlde to the generic state machine object
 * \return state machine current state
 */
TI_UINT32 genSM_GetCurrentState (TI_HANDLE hGenSM)
{
    TGenSM              *pGenSM =       (TGenSM*)hGenSM;

    return pGenSM->uCurrentState;
}