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