|
1 /* |
|
2 * MeasurementSrv.h |
|
3 * |
|
4 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved. |
|
5 * All rights reserved. |
|
6 * |
|
7 * This program and the accompanying materials are made available under the |
|
8 * terms of the Eclipse Public License v1.0 or BSD License which accompanies |
|
9 * this distribution. The Eclipse Public License is available at |
|
10 * http://www.eclipse.org/legal/epl-v10.html and the BSD License is as below. |
|
11 * |
|
12 * Redistribution and use in source and binary forms, with or without |
|
13 * modification, are permitted provided that the following conditions |
|
14 * are met: |
|
15 * |
|
16 * * Redistributions of source code must retain the above copyright |
|
17 * notice, this list of conditions and the following disclaimer. |
|
18 * * Redistributions in binary form must reproduce the above copyright |
|
19 * notice, this list of conditions and the following disclaimer in |
|
20 * the documentation and/or other materials provided with the |
|
21 * distribution. |
|
22 * * Neither the name Texas Instruments nor the names of its |
|
23 * contributors may be used to endorse or promote products derived |
|
24 * from this software without specific prior written permission. |
|
25 * |
|
26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
|
27 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
|
28 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
|
29 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
|
30 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
|
31 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
|
32 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
|
33 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
|
34 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
35 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
|
36 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
37 */ |
|
38 |
|
39 /** \file MeasurementSrv.h |
|
40 * \brief This file include private definitions for the Measurement SRV module. |
|
41 * \author Ronen Kalish |
|
42 * \date 08-November-2005 |
|
43 */ |
|
44 |
|
45 #ifndef __MEASUREMENT_SRV_H__ |
|
46 #define __MEASUREMENT_SRV_H__ |
|
47 |
|
48 #include "TWDriverInternal.h" |
|
49 #include "MacServices_api.h" |
|
50 #include "fsm.h" |
|
51 #include "MeasurementSrvSM.h" |
|
52 |
|
53 /* |
|
54 *********************************************************************** |
|
55 * Constant definitions. |
|
56 *********************************************************************** |
|
57 */ |
|
58 /* Time in milliseconds to receive a command complete for measure start / stop from the FW */ |
|
59 #define MSR_FW_GUARD_TIME 100 |
|
60 #define DEF_SAMPLE_INTERVAL (100) /* expressed in microsec */ |
|
61 #define NOISE_HISTOGRAM_THRESHOLD 100 |
|
62 /* Get param callback flags */ |
|
63 #define MSR_SRV_WAITING_CHANNEL_LOAD_RESULTS 0x01 /* channel load results are still pending */ |
|
64 #define MSR_SRV_WAITING_NOISE_HIST_RESULTS 0x02 /* noise histogram results are still pending */ |
|
65 |
|
66 /* |
|
67 *********************************************************************** |
|
68 * Enums. |
|
69 *********************************************************************** |
|
70 */ |
|
71 |
|
72 |
|
73 /* |
|
74 *********************************************************************** |
|
75 * Typedefs. |
|
76 *********************************************************************** |
|
77 */ |
|
78 |
|
79 /* |
|
80 *********************************************************************** |
|
81 * Structure definitions. |
|
82 *********************************************************************** |
|
83 */ |
|
84 |
|
85 /** \struct measurementSRV_t |
|
86 * \brief This structure contains the measurement SRV object data |
|
87 */ |
|
88 typedef struct |
|
89 { |
|
90 TMediumOccupancy mediumOccupancyResults; /**< channel load results buffer */ |
|
91 TNoiseHistogramResults noiseHistogramResults; /**< noise histogram results buffer */ |
|
92 |
|
93 /* module handles */ |
|
94 TI_HANDLE hOS; /**< OS object handle */ |
|
95 TI_HANDLE hReport; /**< report object handle */ |
|
96 TI_HANDLE hPowerSaveSRV; /**< power save SRV object handle */ |
|
97 TI_HANDLE hCmdBld; /**< Command Builder object handle */ |
|
98 TI_HANDLE hEventMbox; /**< Event Mbox handle */ |
|
99 TI_HANDLE hTimer ; /**< Timer Module handle */ |
|
100 /* CB functions and objects */ |
|
101 TMeasurementSrvCompleteCb measurmentCompleteCBFunc; |
|
102 /**< |
|
103 * upper layer (measurement manager) measurement complete |
|
104 * callback function |
|
105 */ |
|
106 TI_HANDLE measurementCompleteCBObj; /**< |
|
107 * upper layer (measurement manager) measurement complete |
|
108 * callback object |
|
109 */ |
|
110 |
|
111 TCmdResponseCb commandResponseCBFunc; /**< |
|
112 * upper layer command response CB, used for both start |
|
113 * and stop. Passed down to the HAL and called when |
|
114 * the measurement command has been received by the FW |
|
115 */ |
|
116 TI_HANDLE commandResponseCBObj; /**< |
|
117 * object parameter passed to the commandResposeFunc by |
|
118 * the HAL when it is called |
|
119 */ |
|
120 |
|
121 TFailureEventCb failureEventFunc; /**< |
|
122 * upper layer Failure Event CB. |
|
123 * called when the scan command has been Timer Expiry |
|
124 */ |
|
125 TI_HANDLE failureEventObj; /**< |
|
126 * object parameter passed to the failureEventFunc |
|
127 * when it is called |
|
128 */ |
|
129 /* Timers */ |
|
130 TI_HANDLE hRequestTimer[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ]; |
|
131 /**< Timers for different measurement types */ |
|
132 TI_BOOL bRequestTimerRunning[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ]; |
|
133 /**< Indicates whether each request timer is running */ |
|
134 TI_HANDLE hStartStopTimer; /**< Timer for start / stop commands guard */ |
|
135 TI_BOOL bStartStopTimerRunning; /**< |
|
136 * Indicates whether the start / stop command guard |
|
137 * timer is running |
|
138 */ |
|
139 /* Misc stuff */ |
|
140 TI_BOOL bInRequest; /**< |
|
141 * Indicates whether the SM is run within |
|
142 * the measurement request context (if so, to avoid |
|
143 * re-entrance, the complete function shouldn't |
|
144 * be called on failure, but rather an invalid |
|
145 * status should be returned) |
|
146 */ |
|
147 TI_STATUS returnStatus; /**< |
|
148 * Holds the return code to the upper layer |
|
149 * Used to save errors during SM operation. |
|
150 */ |
|
151 TI_BOOL bSendNullDataWhenExitPs; /**< whether to send NULL data frame when exiting |
|
152 * driver mode |
|
153 */ |
|
154 /* state machine */ |
|
155 fsm_stateMachine_t* SM; /**< |
|
156 * state machines for different |
|
157 * scan types |
|
158 */ |
|
159 measurements_SRVSMStates_e SMState; /**< state machine current states */ |
|
160 /* measurement request */ |
|
161 TMeasurementRequest msrRequest; /**< measurement request parameters */ |
|
162 TMeasurementReply msrReply; /**< measurement reply values */ |
|
163 TI_UINT32 requestRecptionTimeStampMs; /**< The time in which the request was received. */ |
|
164 TI_UINT32 timeToRequestExpiryMs; /**< |
|
165 * The duration (in ms) from request receiption |
|
166 * until it should actually start. Request is |
|
167 * discarded if a longer period is required |
|
168 */ |
|
169 TI_UINT8 pendingParamCBs; /**< |
|
170 * a bitmap indicating which get_param CBs are |
|
171 * currently pending (noise histogram and/or |
|
172 * channel load). |
|
173 */ |
|
174 } measurementSRV_t; |
|
175 |
|
176 /* |
|
177 *********************************************************************** |
|
178 * External data definitions. |
|
179 *********************************************************************** |
|
180 */ |
|
181 |
|
182 /* |
|
183 *********************************************************************** |
|
184 * External functions definitions |
|
185 *********************************************************************** |
|
186 */ |
|
187 |
|
188 /** |
|
189 * \author Ronen Kalish\n |
|
190 * \date 08-November-2005\n |
|
191 * \brief Creates the measurement SRV object |
|
192 * |
|
193 * Function Scope \e Public.\n |
|
194 * \param hOS - handle to the OS object.\n |
|
195 * \return a handle to the measurement SRV object, NULL if an error occurred.\n |
|
196 */ |
|
197 TI_HANDLE MacServices_measurementSRV_create( TI_HANDLE hOS ); |
|
198 |
|
199 /** |
|
200 * \author Ronen Kalish\n |
|
201 * \date 08-November-2005\n |
|
202 * \brief Initializes the measurement SRV object |
|
203 * |
|
204 * Function Scope \e Public.\n |
|
205 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
206 * \param hReport - handle to the report object.\n |
|
207 * \param hCmdBld - handle to the Command Builder object.\n |
|
208 * \param hEventMbox - handle to the Event Mbox object.\n |
|
209 * \param hPowerSaveSRV - handle to the power save SRV object.\n |
|
210 * \param hTimer - handle to the Timer module object.\n |
|
211 */ |
|
212 TI_STATUS MacServices_measurementSRV_init (TI_HANDLE hMeasurementSRV, |
|
213 TI_HANDLE hReport, |
|
214 TI_HANDLE hCmdBld, |
|
215 TI_HANDLE hEventMbox, |
|
216 TI_HANDLE hPowerSaveSRV, |
|
217 TI_HANDLE hTimer); |
|
218 |
|
219 /** |
|
220 * \author Ronen Kalish\n |
|
221 * \date 08-November-2005\n |
|
222 * \brief Destroys the measurement SRV object |
|
223 * |
|
224 * Function Scope \e Public.\n |
|
225 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
226 */ |
|
227 void MacServices_measurementSRV_destroy( TI_HANDLE hMeasurementSRV ); |
|
228 |
|
229 /** |
|
230 * \author Ronen Kalish\n |
|
231 * \date 13-November-2005\n |
|
232 * \brief Checks whether a beacon measurement is part of current measurement request |
|
233 * |
|
234 * Function Scope \e Private.\n |
|
235 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
236 * \return TI_TRUE if a beacon measurement is part of current request, TI_FALSE otherwise.\n |
|
237 */ |
|
238 TI_BOOL measurementSRVIsBeaconMeasureIncluded( TI_HANDLE hMeasurementSRV ); |
|
239 |
|
240 /** |
|
241 * \author Ronen Kalish\n |
|
242 * \date 15-November-2005\n |
|
243 * \brief Finds the index for the measurement request with the shortest period |
|
244 * (the one that has now completed).\n |
|
245 * |
|
246 * Function Scope \e Private.\n |
|
247 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
248 * \return index of the measurement request with the shortest duration.\n |
|
249 */ |
|
250 TI_INT32 measurementSRVFindMinDuration( TI_HANDLE hMeasurementSRV ); |
|
251 |
|
252 /** |
|
253 * \author Ronen Kalish\n |
|
254 * \date 15-November-2005\n |
|
255 * \brief Handles an AP discovery timer expiry, by setting necessary values in the |
|
256 * reply struct.\n |
|
257 * |
|
258 * Function Scope \e Private.\n |
|
259 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
260 * \param requestIndex - index of the beacon request in the request structure.\n |
|
261 */ |
|
262 void measurementSRVHandleBeaconMsrComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex ); |
|
263 |
|
264 /** |
|
265 * \author Ronen Kalish\n |
|
266 * \date 15-November-2005\n |
|
267 * \brief Handles a channel load timer expiry, by requesting channel load |
|
268 * results from the FW.\n |
|
269 * |
|
270 * Function Scope \e Private.\n |
|
271 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
272 * \param requestIndex - index of the channel load request in the request structure.\n |
|
273 */ |
|
274 void measurementSRVHandleChannelLoadComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex ); |
|
275 |
|
276 /** |
|
277 * \author Ronen Kalish\n |
|
278 * \date 15-November-2005\n |
|
279 * \brief Handles a nois histogram timer expiry, by requesting noise histogram |
|
280 * reaults from the FW.\n |
|
281 * |
|
282 * Function Scope \e Private.\n |
|
283 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
284 * \param requestIndex - indexof the beacon request in the request structure.\n |
|
285 */ |
|
286 void measurementSRVHandleNoiseHistogramComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex ); |
|
287 |
|
288 /** |
|
289 * \author Ronen Kalish\n |
|
290 * \date 16-November-2005\n |
|
291 * \brief Checks whether all measuremtn types had completed and all param CBs had been called.\n |
|
292 * |
|
293 * Function Scope \e Public.\n |
|
294 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
295 * \param status - the get_param call status.\n |
|
296 * \param CB_buf - pointer to the results buffer (already on the measurement SRV object) |
|
297 */ |
|
298 TI_BOOL measurementSRVIsMeasurementComplete( TI_HANDLE hMeasurementSRV ); |
|
299 |
|
300 /** |
|
301 * \author Ronen Kalish\n |
|
302 * \date 17-November-2005\n |
|
303 * \brief Finds a measure type index in the measure request array.\n |
|
304 * |
|
305 * Function Scope \e Public.\n |
|
306 * \param hMeasurementSRV - handle to the measurement SRV object.\n |
|
307 * \param type - the measure type to look for.\n |
|
308 * \return the type index, -1 if not found.\n |
|
309 */ |
|
310 TI_INT32 measurementSRVFindIndexByType( TI_HANDLE hMeasurementSRV, EMeasurementType type ); |
|
311 |
|
312 /**************************************************************************************** |
|
313 * measurementSRVRegisterFailureEventCB * |
|
314 **************************************************************************************** |
|
315 DESCRIPTION: Registers a failure event callback for scan error notifications. |
|
316 |
|
317 |
|
318 INPUT: - hMeasurementSRV - handle to the Measurement SRV object. |
|
319 - failureEventCB - the failure event callback function.\n |
|
320 - hFailureEventObj - handle to the object passed to the failure event callback function. |
|
321 |
|
322 OUTPUT: |
|
323 RETURN: void. |
|
324 ****************************************************************************************/ |
|
325 void measurementSRVRegisterFailureEventCB( TI_HANDLE hMeasurementSRV, |
|
326 void * failureEventCB, TI_HANDLE hFailureEventObj ); |
|
327 |
|
328 void measurementSRV_restart( TI_HANDLE hMeasurementSRV); |
|
329 |
|
330 |
|
331 #endif /* __MEASUREMENT_SRV_H__ */ |
|
332 |