1 /*
2 * GenSM.c
3 *
4 * Copyright(c) 1998 - 2009 Texas Instruments. All rights reserved.
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
16 * distribution.
17 * * Neither the name Texas Instruments nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 */
33
34 /** \file GenSM.c
35 * \brief Generic state machine implementation
36 *
37 * \see GenSM.h
38 */
39
40
41 #define __FILE_ID__ FILE_ID_128
42 #include "tidef.h"
43 #include "osApi.h"
44 #include "report.h"
45 #include "GenSM.h"
46
47
48 /**
49 * \fn genSM_Create
50 * \brief Cerates a generic state machine object
51 *
52 * Cerates a generic state machine object. Allocates system resources.
53 *
54 * \note event/action matrix and debug descriptions are used by reference, and are not copied!
55 * \param hOS - handle to the OS object
56 * \return Handle to the generic state machine object
57 * \sa GenSM_Unload, GenSM_Init, genSM_SetDefaults
58 */
genSM_Create(TI_HANDLE hOS)59 TI_HANDLE genSM_Create (TI_HANDLE hOS)
60 {
61 TGenSM *pGenSM = NULL;
62
63 /* Allocate object storage */
64 pGenSM = os_memoryAlloc (hOS, sizeof(TGenSM));
65 if (NULL != pGenSM)
66 {
67 /* Store OS handle */
68 pGenSM->hOS = hOS;
69 }
70
71 return (TI_HANDLE)pGenSM;
72 }
73
74 /**
75 * \fn genSM_Unload
76 * \brief Unloads a generic state machine object
77 *
78 * Unloads a generic state machine object. Frees system resources consumed by the object.
79 *
80 * \param hGenSM - hanlde to the generic state machine object
81 * \return None
82 * \sa GenSM_Create
83 */
genSM_Unload(TI_HANDLE hGenSM)84 void genSM_Unload (TI_HANDLE hGenSM)
85 {
86 TGenSM *pGenSM = (TGenSM*)hGenSM;
87
88 /* free the generic state machine object storage */
89 os_memoryFree (pGenSM->hOS, hGenSM, sizeof (TGenSM));
90 }
91
92 /**
93 * \fn genSM_Init
94 * \brief Initializes the generic state machine object
95 *
96 * Initializes the generic state machine object. Store handles to other modules.
97 *
98 * \param hGenSM - hanlde to the generic state machine object
99 * \param hReport - handle to the report module
100 * \return None
101 * \sa GenSM_Create, genSM_SetDefaults
102 */
genSM_Init(TI_HANDLE hGenSM,TI_HANDLE hReport)103 void genSM_Init (TI_HANDLE hGenSM, TI_HANDLE hReport)
104 {
105 TGenSM *pGenSM = (TGenSM*)hGenSM;
106
107 /* store report handle */
108 pGenSM->hReport = hReport;
109 }
110
111 /**
112 * \fn genSM_SetDefaults
113 * \brief Set default values to the generic state machine
114 *
115 * Set default values to the generic state machine
116 *
117 * \note event/action matrix and debug descriptions are used by reference, and are not copied!
118 * \param hGenSM - hanlde to the generic state machine object
119 * \param uStateNum - number of states
120 * \param uEventNum - number of events
121 * \param pMatrix - pointer to the event/actions matrix
122 * \param uInitialState - the initial state
123 * \param pGenSMName - a string describing the state machine, for debug prints
124 * \param pStateDesc - strings describing the state machine states, for debug prints
125 * \param pEventDesc - strings describing the state machine events, for debug prints
126 * \param uModuleLogIndex - Log index used by the module using the state machine
127 * \return None
128 * \sa genSM_Create, genSM_Init
129 */
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)130 void genSM_SetDefaults (TI_HANDLE hGenSM, TI_UINT32 uStateNum, TI_UINT32 uEventNum,
131 TGenSM_matrix pMatrix, TI_UINT32 uInitialState, TI_INT8 *pGenSMName,
132 TI_INT8 **pStateDesc, TI_INT8 **pEventDesc, TI_UINT32 uModuleLogIndex)
133 {
134 TGenSM *pGenSM = (TGenSM*)hGenSM;
135
136 /* set values */
137 pGenSM->uStateNum = uStateNum;
138 pGenSM->uEventNum = uEventNum;
139 pGenSM->tMatrix = pMatrix;
140 pGenSM->uCurrentState = uInitialState;
141 pGenSM->pGenSMName = pGenSMName;
142 pGenSM->pStateDesc = pStateDesc;
143 pGenSM->pEventDesc = pEventDesc;
144 pGenSM->uModuleLogIndex = uModuleLogIndex;
145 pGenSM->bEventPending = TI_FALSE;
146 pGenSM->bInAction = TI_FALSE;
147 }
148
genSM_Event(TI_HANDLE hGenSM,TI_UINT32 uEvent,void * pData)149 void genSM_Event (TI_HANDLE hGenSM, TI_UINT32 uEvent, void *pData)
150 {
151 TGenSM *pGenSM = (TGenSM*)hGenSM;
152 TGenSM_actionCell *pCell;
153
154 if (pGenSM == NULL)
155 {
156 TRACE0(pGenSM->hReport, REPORT_SEVERITY_ERROR , "genSM_Event: Handle is NULL!!\n");
157 return;
158 }
159
160 #ifdef TI_DBG
161 /* sanity check */
162 if (uEvent >= pGenSM->uEventNum)
163 {
164 TRACE3(pGenSM->hReport, REPORT_SEVERITY_ERROR , "genSM_Event: module: %d received event %d, which is out of events boundry %d\n", pGenSM->uModuleLogIndex, uEvent, pGenSM->uEventNum);
165 }
166 if (TI_TRUE == pGenSM->bEventPending)
167 {
168 TRACE3(pGenSM->hReport, REPORT_SEVERITY_ERROR , "genSM_Event: module: %d received event %d, when event %d is pending execution!\n", pGenSM->uModuleLogIndex, uEvent, pGenSM->uEvent);
169 }
170 #endif
171
172 /* mark that an event is pending */
173 pGenSM->bEventPending = TI_TRUE;
174
175 /* save event and data */
176 pGenSM->uEvent = uEvent;
177 pGenSM->pData = pData;
178
179 /* if an event is currently executing, return (new event will be handled when current event is done) */
180 if (TI_TRUE == pGenSM->bInAction)
181 {
182 TRACE1(pGenSM->hReport, REPORT_SEVERITY_INFORMATION , ": module: %d delaying execution of event \n", pGenSM->uModuleLogIndex);
183 return;
184 }
185
186 /* execute events, until none is pending */
187 while (TI_TRUE == pGenSM->bEventPending)
188 {
189 /* get the cell pointer for the current state and event */
190 pCell = &(pGenSM->tMatrix[ (pGenSM->uCurrentState * pGenSM->uEventNum) + pGenSM->uEvent ]);
191
192
193 /* print state transition information */
194 TRACE4(pGenSM->hReport, REPORT_SEVERITY_INFORMATION, "genSM_Event: module %d <currentState = %d, event = %d> --> nextState = %d\n", pGenSM->uModuleLogIndex, pGenSM->uCurrentState, uEvent, pCell->uNextState);
195
196 /* mark that event execution is in place */
197 pGenSM->bInAction = TI_TRUE;
198
199 /* mark that pending event is being handled */
200 pGenSM->bEventPending = TI_FALSE;
201
202 /* update current state */
203 pGenSM->uCurrentState = pCell->uNextState;
204
205 /* run transition function */
206 (*(pCell->fAction)) (pGenSM->pData);
207
208 /* mark that event execution is complete */
209 pGenSM->bInAction = TI_FALSE;
210 }
211 }
212
213 /**
214 * \fn genSM_GetCurrentState
215 * \brief retrieves the state machine current state
216 *
217 * retrieves the state machine current state
218 *
219 * \param hGenSM - hanlde to the generic state machine object
220 * \return state machine current state
221 */
genSM_GetCurrentState(TI_HANDLE hGenSM)222 TI_UINT32 genSM_GetCurrentState (TI_HANDLE hGenSM)
223 {
224 TGenSM *pGenSM = (TGenSM*)hGenSM;
225
226 if (pGenSM == NULL)
227 {
228 TRACE0(pGenSM->hReport, REPORT_SEVERITY_ERROR , "genSM_GetCurrentState: Handle is NULL!!\n");
229 return 0;
230 }
231 return pGenSM->uCurrentState;
232 }
233