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