system/wlan/ti/sta_dk_4_0_4_32/common/src/TNETW_Driver/MacServices/src/ScanServer/ScanSrv.h

   1 /** \file ScanSrv.h
   2  *  \brief This file include private definitions for the scan SRV module.
   3  *  \author Ronen Kalish
   4  *  \date 29-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 __SCANSRV_H__
  42 #define __SCANSRV_H__
  43
  44 #include "MacServices_api.h"
  45 #include "fsm.h"
  46 #include "whalCtrl_api.h"
  47 #include "ScanSrvSM.h"
  48
  49 /*
  50  ***********************************************************************
  51  *  Constant definitions.
  52  ***********************************************************************
  53  */
  54 /* guard time for scan (added to calculated scan duration) */
  55 #define SCAN_SRV_FW_GUARD_TIME_MS                       62000
  56 /* module name for driver mode requests */
  57 #define SCAN_SRV_NAME                                   "SSRV"
  58
  59
  60 /*
  61  ***********************************************************************
  62  *  Enums.
  63  ***********************************************************************
  64  */
  65
  66
  67 /*
  68  ***********************************************************************
  69  *  Typedefs.
  70  ***********************************************************************
  71  */
  72
  73 /*
  74  ***********************************************************************
  75  *  Structure definitions.
  76  ***********************************************************************
  77  */
  78
  79 /** \struct scanSRV_t
  80  * \brief This structure contains the scan SRV object data
  81  */
  82 typedef struct
  83 {
  84     TI_HANDLE           hOS;                            /**< OS object handle */
  85     TI_HANDLE           hReport;                        /**< report object handle */
  86     TI_HANDLE           hPowerSrv;                     /**< power Server object handle */
  87     TI_HANDLE           hHalCtrl;                       /**< HAL ctrl object handle */
  88     scan_srvCompleteCB_t scanCompleteNotificationFunc;  /**<
  89                                                          * upper layer (scan concentrator) scan complete
  90                                                          * callback function
  91                                                          */
  92     TI_HANDLE           scanCompleteNotificationObj;    /**<
  93                                                          * upper layer (scan concentrator) scan complete
  94                                                          * callback function
  95                                                          */
  96
  97     CmdResponseCB_t     commandResponseFunc;            /**<
  98                                                          * upper layer command response CB. Passed down into the HAL
  99                                                          * and called when the scan command has been received by the FW
 100                                                          */
 101     TI_HANDLE           commandResponseObj;             /**<
 102                                                          * object parameter passed to the commandResposeFunc by the HAL
 103                                                          * when it is called
 104                                                          */
 105     failureEventCB_t    failureEventFunc;               /**<
 106                                                          * upper layer Failure Event CB.
 107                                                          * called when the scan command has been Timer Expiry
 108                                                          */
 109     TI_HANDLE           failureEventObj;                /**<
 110                                                          * object parameter passed to the failureEventFunc
 111                                                          * when it is called
 112                                                          */
 113     UINT16              SPSScanResult;                  /**<
 114                                                          * bitmap indicating which channels were scanned
 115                                                          * in an SPS scan
 116                                                          */
 117     BOOLEAN             bTSFError;                      /** indicates whether a TSF error occured */                                                        /**<
 118                                                          * scan result: indicates a TSF error event and
 119                                                          * which channels were scanned in SPS
 120                                                          */
 121     BOOLEAN             bDtimOverlapping;               /**< Indicates whether the scan is overlapping DTIM */
 122     BOOLEAN             bExitFromDriverMode;            /**<
 123                                                          * Indicates whether to exit driver mode once scan
 124                                                          * is finished
 125                                                          */
 126     BOOLEAN             bSendNullData;                  /**<
 127                                                          * Indicates whether to send Null data when exiting driver
 128                                                          * mode once scan is finished
 129                                                          */
 130     BOOLEAN             bScanOnDriverModeFailure;       /**<
 131                                                          * Indicates whether to scan if driver mode entry
 132                                                          * wasn't successful
 133                                                          */
 134     BOOLEAN             bHighPriority;                  /**<
 135                                                          * Indicates whether to request high priority
 136                                                          * (overlapping DTIM) scan
 137                                                          */
 138     BOOLEAN             bSPSScan;                       /**<
 139                                                          * whether the running scan type is SPS (TRUE)
 140                                                          * or something else (FALSE). Used to stop a
 141                                                          * running scan.
 142                                                          */
 143     scan_Params_t*      scanParams;                     /**< scan parameters */
 144     TI_HANDLE           timer;                          /**< scan operation timer */
 145     BOOLEAN             bTimerRunning;                  /**< whether the above timer is running */
 146     BOOLEAN             bInRequest;                     /**<
 147                                                          * Indicates whether the SM is run within
 148                                                          * the scan request context (if so, to avoid
 149                                                          * re-entrance, the complete function shouldn't
 150                                                          * be called on failure, but rather an invalid
 151                                                          * status should be returned)
 152                                                          */
 153     TI_STATUS           returnStatus;                   /**<
 154                                                          * Holds the return code to the upper layer
 155                                                          * Used to save errors during SM operation.
 156                                                          */
 157     /* state machine */
 158     fsm_stateMachine_t*     SM;                         /**<
 159                                                          * state machines for different
 160                                                          * scan types
 161                                                          */
 162     scan_SRVSMStates_e      SMState;                    /**<
 163                                                          * state machine current states
 164                                                          * for different scan types
 165                                                          */
 166     PowerMgr_802_11_PsMode_e psRequest;                 /**<
 167                                                          * Indicates if PS was requested or not
 168                                                          * for current scan
 169                                                          */
 170         UINT32                                  numberOfNoScanCompleteToRecovery;
 171                                                                                                                 /**<
 172                                                                                                                  * The number of consecutive no scan complete
 173                                                                                                                  * that will trigger a recovery notification
 174                                                                                                                  */
 175         UINT32                                  currentNumberOfConsecutiveNoScanCompleteEvents;
 176                                                                                                                 /**<
 177                                                                                                                  * The number of consecutivre no scan complete
 178                                                                                                                  * events at present
 179                                                                                                                  */
 180     BOOLEAN                 bNoScanCompleteFlag;        /**<
 181                                                          * Indicates if the last event was start scan
 182                                                          * (true) or no scan complete (false) to be able
 183                                                          * to nullify correctly the above counter */
 184     UINT32                                      uTriggeredScanTimeOut;      /**<
 185                                                          * Time out for starting triggered scan between
 186                                                          * 2 channels */
 187 } scanSRV_t;
 188
 189 /*
 190  ***********************************************************************
 191  *  External data definitions.
 192  ***********************************************************************
 193  */
 194
 195 /*
 196  ***********************************************************************
 197  *  External functions definitions
 198  ***********************************************************************
 199  */
 200
 201 /**
 202  * \author Yuval Adler\n
 203  * \date 16-Oct-2004\n
 204  * \brief Creates the scan SRV object
 205  *
 206  * Function Scope \e Public.\n
 207  * \param hOS - handle to the OS object.\n
 208  * \return a handle to the scan SRV object, NULL if an error occurred.\n
 209  */
 210 TI_HANDLE MacServices_scanSRV_create( TI_HANDLE hOS );
 211
 212 /**
 213  * \author Yuval Adler\n
 214  * \date 29-Dec-2004\n
 215  * \brief Finalizes the scan SRV module (releasing memory and timer)
 216  *
 217  * Function Scope \e Public.\n
 218  * \param hScanSRV - handle to the scan SRV object.\n
 219  */
 220 void MacServices_scanSRV_destroy( TI_HANDLE hScanSRV );
 221
 222 /**
 223  * \author Yuval Adler\n
 224  * \date 29-Dec-2004\n
 225  * \brief Initializes the scan SRV module, registers SCAN_COMPLETE to HAL.
 226  *
 227  * Function Scope \e Public.\n
 228  * \param hScanSRV - handle to the scan SRV object.\n
 229  * \param hReport - handle to the report object.\n
 230  * \param hPowerMngr - handle to the power manager object.\n
 231  * \param hHalCtrl - handle to the HAL ctrl object.\n
 232   */
 233 void MacServices_scanSRV_init( TI_HANDLE hMacServices, TI_HANDLE hReport, TI_HANDLE hHalCtrl);
 234
 235 /**
 236  * \author Ronen Kalish\n
 237  * \date 26-July-2006\n
 238  * \brief Configures the scan SRV module with initialization values
 239  *
 240  * Function Scope \e Public.\n
 241  * \param hScanSRV - handle to the scan SRV object.\n
 242  * \param hReport - handle to the report object.\n
 243  * \param hHalCtrl - handle to the HAL ctrl object.\n
 244   */
 245 void MacServices_scanSrv_config( TI_HANDLE hMacServices, scanSrvInitParams_t* pInitParams );
 246
 247 /**
 248  * \author Ronen Kalish\n
 249  * \date 29-Dec-2004\n
 250  * \brief Calculates the maximal time required for a scan operation
 251  *
 252  * Function Scope \e Public.\n
 253  * \param hScanSRV - handle to the scan SRV object.\n
 254  * \param scanParams - the scan parameters
 255  * \param bConsiderDTIM - whether this scan overlaps DTIM
 256  * \return the time (in milliseconds)
 257  */
 258 UINT32 MacServices_scanSRVcalculateScanTimeout( TI_HANDLE hScanSrv, scan_Params_t* scanParams, BOOLEAN bConsiderDTIM );
 259
 260 /**
 261  * \author Ronen Kalish\n
 262  * \date 16-Jan-2005\n
 263  * \brief Convert time units (1024 usecs) to millisecs
 264  *
 265  * Function Scope \e Private.\n
 266  * \param tu - the time in time units
 267  * \return the time in milliseconds
 268  */
 269 UINT32 MacServices_scanSRVConvertTUToMsec( UINT32 tu );
 270
 271 /**
 272  * \author Yuval Adler\n
 273  * \date 27-Sep-2005\n
 274  * \brief This function is the CB which is called as response to 'StartScan' or 'StopScan' \n.
 275  *        here we check if there is a GWSI command response , and call it if necessary .\n
 276  * Function Scope \e Private.\n
 277  * \param hScanSrv - handle to the scan SRV object.\n
 278  * \param MboxStatus - mailbox status. \n
 279  */
 280
 281 void MacServices_scanSRVCommandMailBoxCB(TI_HANDLE hScanSrv,UINT16 MboxStatus);
 282
 283
 284 /**
 285  * \brief Registers a failure event callback for scan error notifications.
 286  *
 287  * Function Scope \e Public.\n
 288  * \param hMacServices - handle to the MacServices object.\n
 289  * \param failureEventCB - the failure event callback function.\n
 290  * \param hFailureEventObj - handle to the object passed to the failure event callback function.\n
 291  */
 292 void scanSRV_registerFailureEventCB( TI_HANDLE hScanSRV,
 293                                      void * failureEventCB, TI_HANDLE hFailureEventObj );
 294
 295 void scanSRV_restart( TI_HANDLE hScanSRV);
 296
 297 #endif /* __SCANSRV_H__ */