1/** \file ScrApi.h
2 *  \brief This file include public definitions for the SCR module, comprising its API.
3 *  \author Ronen Kalish
4 *  \date 01-Dec-2004
5 */
6 /****************************************************************************
7**+-----------------------------------------------------------------------+**
8**|                                                                       |**
9**| Copyright(c) 1998 - 2008 Texas Instruments. All rights reserved.      |**
10**| All rights reserved.                                                  |**
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****************************************************************************/
40
41#ifndef __SCRAPI_H__
42#define __SCRAPI_H__
43
44#include "osTIType.h"
45
46/*
47 ***********************************************************************
48 *	Constant definitions.
49 ***********************************************************************
50 */
51
52/*
53 ***********************************************************************
54 *	Enums.
55 ***********************************************************************
56 */
57/** \enum scr_modeId_e
58 * \brief enumerates the different modes available in the system
59 */
60typedef enum
61{
62	SCR_MID_NORMAL = 0,			/**< Normal mode	  */
63	SCR_MID_SG,					/**< Soft Gemini mode */
64	SCR_MID_NUM_OF_MODES
65} scr_modeId_e;
66
67/** \enum scr_groupId_e
68 * \brief enumerates the different groups available in the system
69 */
70typedef enum
71{
72    SCR_GID_IDLE = 0,           /**< STA is idle */
73    SCR_GID_INTER_SCAN,         /**< STA is disconnected, SME waits for next scan */
74    SCR_GID_CONNECT,            /**< STA is trying to conenct */
75    SCR_GID_CONNECTED,          /**< STA is connected */
76    SCR_GID_ROAMING,            /**< STA is performing roaming to another AP */
77    SCR_GID_NUM_OF_GROUPS
78} scr_groupId_e;
79
80
81/** \enum scr_clientId_e
82 * \brief enumerates the different clients available in the system
83 */
84typedef enum
85{
86    SCR_CID_APP_SCAN = 0,    /* lowest priority */
87    SCR_CID_DRIVER_FG_SCAN,
88	SCR_CID_CONT_SCAN,
89    SCR_CID_EXC_MEASURE,
90    SCR_CID_BASIC_MEASURE,
91	SCR_CID_CONNECT,
92    SCR_CID_IMMED_SCAN,
93	SCR_CID_SWITCH_CHANNEL,		/* highest priority */
94	SCR_CID_NUM_OF_CLIENTS,
95    SCR_CID_NO_CLIENT
96} scr_clientId_e;
97
98/** \enum scr_clientRequestStatus_e
99 * \brief enumerates the status reports the client may receive
100 */
101typedef enum
102{
103	SCR_CRS_RUN = 0,            /**< the client can use the channel */
104    SCR_CRS_PEND,               /**< the channel is in use, The client may wait for it. */
105    SCR_CRS_ABORT,              /**< client should abort it's use of the channel */
106    SCR_CRS_FW_RESET            /**< Notification of recovery (client should elect what to do) */
107} scr_clientRequestStatus_e;
108
109/** \enum scr_pendReason_e
110 * \brief enumerates the different reasons which can cause a client request to return with pend status.
111 */
112typedef enum
113{
114    SCR_PR_OTHER_CLIENT_ABORTING = 0,		/**<
115											 * The requesting client is waiting for a client with lower priority
116											 * to abort operation
117											 */
118	SCR_PR_OTHER_CLIENT_RUNNING,				/**<
119											 * The requesting client is waiting for a client that cannot be aborted
120											 * to finish using the channel.
121											 */
122    SCR_PR_DIFFERENT_GROUP_RUNNING,         /**< The current SCR group is different than the client's group */
123	SCR_PR_NONE                             /**< The client is not pending */
124} scr_pendReason_e;
125
126/*
127 ***********************************************************************
128 *	Typedefs.
129 ***********************************************************************
130 */
131
132 /** \typedef scr_abortReason_e
133  * \brief Defines the function prototype a client should register as callback.
134  */
135typedef void (*scr_callback_t)( TI_HANDLE hClient,
136                                scr_clientRequestStatus_e requestStatus,
137                                scr_pendReason_e pendReason );
138
139/*
140 ***********************************************************************
141 *	Structure definitions.
142 ***********************************************************************
143 */
144
145/*
146 ***********************************************************************
147 *	External data definitions.
148 ***********************************************************************
149 */
150
151/*
152 ***********************************************************************
153 *	External functions definitions
154 ***********************************************************************
155 */
156
157/**
158 * \author Ronen Kalish\n
159 * \date 01-Dec-2004\n
160 * \brief Creates the SCR object
161 *
162 * Function Scope \e Public.\n
163 * \param hOS - handle to the OS object.\n
164 * \return a handle to the SCR object.\n
165 */
166TI_HANDLE scr_create( TI_HANDLE hOS );
167
168/**
169 * \author Ronen Kalish\n
170 * \date 01-Dec-2004\n
171 * \brief Finalizes the SCR object (freeing memory)
172 *
173 * Function Scope \e Public.\n
174 * \param hScr - handle to the SCR object.\n
175 */
176void scr_release( TI_HANDLE hScr );
177
178/**
179 * \author Ronen Kalish\n
180 * \date 01-Dec-2004\n
181 * \brief Initializes the SCR object
182 *
183 * Function Scope \e Public.\n
184 * \param hScr - handle to the SCR object.\n
185 * \param hReport - handle to the report module.\n
186 */
187void scr_init( TI_HANDLE hScr, TI_HANDLE hReport );
188
189/**
190 * \author Ronen Kalish\n
191 * \date 01-Dec-2004\n
192 * \brief Registers the callback function to be used per client.
193 *
194 * Function Scope \e Public.\n
195 * \param hScr - handle to the SCR object.\n
196 * \param client - the client ID.\n
197 * \param callbackFunc - the address of the callback function to use.\n
198 * \param callbackObj - the handle of the object to pass to the callback function (the client object).\n
199 */
200void scr_registerClientCB( TI_HANDLE hScr,
201                           scr_clientId_e client,
202                           scr_callback_t callbackFunc,
203                           TI_HANDLE callbackObj );
204
205/**
206 * \author Ronen Kalish\n
207 * \date 01-Dec-2004\n
208 * \brief Notifies the running process upon a firmware reset.
209 *
210 * Function Scope \e Public.\n
211 * \param hScr - handle to the SCR object.\n
212 */
213void scr_notifyFWReset( TI_HANDLE hScr );
214
215/**
216 * \author Ronen Kalish\n
217 * \date 27-April-2005\n
218 * \brief Changes the current SCR group.\n
219 *
220 * Function Scope \e Public.\n
221 * \param hScr - handle to the SCR object.\n
222 * \param newGroup - the new group to use.\n
223 */
224void scr_setGroup( TI_HANDLE hScr, scr_groupId_e newGroup );
225
226/**
227 * \author Yuval Adler\n
228 * \date 23-1l-2005\n
229 * \brief Changes the current SCR mode. This function is called from Soft Gemini module only \n
230 *	      when changing mode - clients that are not valid in the new group/mode are aborted	 \n
231 *
232 * Function Scope \e Public.\n
233 * \param hScr - handle to the SCR object.\n
234 * \param newMode - the new mode to use.\n
235 */
236void scr_setMode( TI_HANDLE hScr, scr_modeId_e newMode );
237
238/**
239 * \author Ronen Kalish\n
240 * \date 01-Dec-2004\n
241 * \brief Request the channel use by a client
242 *
243 * Function Scope \e Public.\n
244 * \param hScr - handle to the SCR object.\n
245 * \param client - the client ID requesting the channel.\n
246 * \param pPendReason - the reason for a pend reply.\n
247 * \return The request status.\n
248 * \retval SCR_CRS_REJECT the channel cannot be allocated to this client.
249 * \retval SCR_CRS_PEND the channel is currently busy, and this client had been placed on the waiting list.
250 * \retval SCR_CRS_RUN the channel is allocated to this client.
251 */
252scr_clientRequestStatus_e scr_clientRequest( TI_HANDLE hScr, scr_clientId_e client, scr_pendReason_e* pPendReason );
253
254/**
255 * \author Ronen Kalish\n
256 * \date 01-Dec-2004\n
257 * \brief Notifies the SCR that the client doe not require the channel any longer
258 *
259 * This function can be called both by clients that are in possession of the channel, and by
260 * clients that are pending to use the channel.\n
261 * Function Scope \e Public.\n
262 * \param hScr - handle to the SCR object.\n
263 * \param client - the client releasing the channel.\n
264 * \return OK if successful, NOK otherwise.\n
265 */
266void scr_clientComplete( TI_HANDLE hScr, scr_clientId_e client );
267
268#endif /* __SCRAPI_H__ */
269