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 */ 60 typedef 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 */ 70 typedef 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 */ 84 typedef 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 */ 101 typedef 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 */ 112 typedef 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 */ 135 typedef 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 */ 166 TI_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 */ 176 void 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 */ 187 void 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 */ 200 void 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 */ 213 void 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 */ 224 void 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 */ 236 void 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 */ 252 scr_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 */ 266 void scr_clientComplete( TI_HANDLE hScr, scr_clientId_e client ); 267 268 #endif /* __SCRAPI_H__ */ 269