hardware/ti/wlan/wl1271/stad/src/Sta_Management/ScanCncn.h

   1 /*
   2  * ScanCncn.h
   3  *
   4  * Copyright(c) 1998 - 2010 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  ScanCncn.h
  35  *  \brief Scan concentartor module API
  36  *
  37  *  \see   ScanCncn.c
  38  */
  39
  40 #ifndef __SCANCNCN_H__
  41 #define __SCANCNCN_H__
  42
  43 #include "osTIType.h"
  44 #include "TWDriver.h"
  45 #include "scrApi.h"
  46 #include "mlmeApi.h"
  47
  48 #define SCAN_CNCN_APP_SCAN_TABLE_ENTRIES 64
  49
  50 /** \enum EScanCncnClient
  51  * \brief       Scan Concentrator Client
  52  *
  53  * \par Description
  54  * Enumerates the different possible clients requesting scan from the scan concentrator
  55  *
  56  * \sa
  57  */
  58 typedef enum
  59 {
  60 /*      0       */      SCAN_SCC_ROAMING_IMMED,         /**< Indicates a scan from the immediate scan for a roaming client */
  61 /*      1       */      SCAN_SCC_ROAMING_CONT,          /**< Indicates a scan from the continuous scan for a roaming client */
  62 /*      2       */      SCAN_SCC_DRIVER,                /**< Indicates a scan from the driver client (SME scan) */
  63 /*      3       */      SCAN_SCC_APP_PERIODIC,          /**< Indicates application (user) periodic scan */
  64 /*      4       */      SCAN_SCC_APP_ONE_SHOT,          /**< Indicates application (user) one shot scan */
  65 /*      5       */      SCAN_SCC_NUM_OF_CLIENTS,        /**< Number of scan clients (used internally) */
  66 /*      6       */      SCAN_SCC_NO_CLIENT              /**< No valid scan clients (used internally) */
  67
  68 } EScanCncnClient;
  69
  70 /** \enum EScanCncnResultStatus
  71  * \brief       Scan Concentrator Result Status
  72  *
  73  * \par Description
  74  * Enumerates the possible scan result statuses
  75  *
  76  * \sa
  77  */
  78 typedef enum
  79 {
  80 /*      0       */      SCAN_CRS_RECEIVED_FRAME = 0,            /**< Scan is still running; management frame information is passed. */
  81 /*      1       */      SCAN_CRS_SCAN_COMPLETE_OK,              /**< Scan completed successfully */
  82 /*      2       */      SCAN_CRS_SCAN_RUNNING,                  /**< Scan started successfully and now is running */
  83 /*      3       */      SCAN_CRS_SCAN_FAILED,                   /**<
  84                                                                                                         * scan failed due to unexpected situation (SCR reject, no
  85                                                                                                         * channels available, scan SRV returned TI_NOK, etc)
  86                                                                                                         */
  87 /*      4       */      SCAN_CRS_SCAN_STOPPED,                  /**< scan stopped by user */
  88 /*      5       */      SCAN_CRS_TSF_ERROR,                     /**< TSF error (AP recovery) occurred (for SPS only):
  89                                                                                                         * SPS was not performed because current TSF value is less than designated TSF value.
  90                                                                                                         */
  91 /*      6       */      SCAN_CRS_SCAN_ABORTED_FW_RESET,         /**< scan aborted due to FW reset */
  92 /*      7       */      SCAN_CRS_SCAN_ABORTED_HIGHER_PRIORITY,  /**< Scan was aborted because of a higher priority client request of the channel (switched channel) */
  93 /*      8       */      SCAN_CRS_NUM_OF_RES_STATUS              /**< number of possible result status */
  94
  95 } EScanCncnResultStatus;
  96
  97 /** \struct TScanFrameInfo
  98  * \brief Scan Fram Information
  99  *
 100  * \par Description
 101  * This structure contains a single frame information, returned by the result CB when a frame is available.
 102  * It is used to pass scan results (beacons and probe responses).
 103  *
 104  * \sa
 105  */
 106 typedef struct
 107 {
 108     TMacAddr*           bssId;              /* BSSID (MAC address) of the AP from which the frame was received */
 109     mlmeFrameInfo_t*    parsedIEs;          /* Information elements in the frame, which is parsed */
 110     ERadioBand          band;               /* Band on which the frame was received */
 111     TI_UINT8            channel;            /* Channel on which the frame was received */
 112     TI_UINT32           staTSF;             /* TSF of the station when the frame was received */
 113     TI_INT8             rssi;               /* RSSI level at which frame was received */
 114     TI_INT8             snr;                /* SNR level at which frame was received */
 115     ERate               rate;               /* Bitrate at which frame was received */
 116     TI_UINT8*           buffer;             /* Frame information elements, unparsed */
 117     TI_UINT16           bufferLength;       /* Length of the frame unparsed information elements */
 118 } TScanFrameInfo;
 119
 120  /** \typedef TScanResultCB
 121   * \brief Defines the function prototype for the scan result callback
 122   * (notification by the scan concentrator to a client of either a scan
 123   * termination or a result frame received).
 124   */
 125 /**
 126  * \brief       Scan Result CB
 127  *
 128  * \param  clientObj                                    - TWD module object handle
 129  * \param  status                               - TID number
 130  * \param  frameInfo                            - Policy : Enable / Disable
 131  * \param  SPSStatus                                    - Mac address of: SA as receiver / RA as initiator
 132  * \return void
 133  *
 134  * \par Description
 135  * Defines the function prototype for the scan result callback
 136  * (notification by the scan concentrator to a client of either a scan termination or a result frame received)
 137  * This CB is egistered by each client and invoked by the scan concentrator, passes scan results to the caller.
 138  *
 139  * \sa
 140  */
 141 typedef void (*TScanResultCB) (TI_HANDLE clientObj, EScanCncnResultStatus status,
 142                                TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus);
 143
 144
 145 TI_HANDLE               scanCncn_Create (TI_HANDLE hOS);
 146 void                    scanCncn_Destroy (TI_HANDLE hScanCncn);
 147 void                    scanCncn_Init (TStadHandlesList *pStadHandles);
 148 void                    scanCncn_SetDefaults (TI_HANDLE hScanCncn, TScanCncnInitParams* pScanCncnInitParams);
 149 void                    scanCncn_SwitchToConnected (TI_HANDLE hScanCncn);
 150 void                    scanCncn_SwitchToNotConnected (TI_HANDLE hScanCncn);
 151 void                    scanCncn_SwitchToIBSS (TI_HANDLE hScanCncn);
 152 /**
 153  * \brief Starts a one-shot scan operation
 154  *
 155  * \param  hScanCncn    - Handle to the scan concentrator object
 156  * \param  eClient              - The client requesting the scan operation
 157  * \param  pScanParams  - Parameters for the requested scan
 158  * \return Scan Concentrator Result Status:
 159  * SCAN_CRS_SCAN_RUNNING - scan started successfully and is now running
 160  * SCAN_CRS_SCAN_FAILED - scan failed to start due to an unexpected error
 161  *
 162  * \par Description
 163  * Starts a one-shot scan operation:
 164  *  - copies scan params to scan concentrator object
 165  *  - copies current SSID for roaming scans
 166  *  - verifies the requested channels with the reg doamin
 167  *  - if needed, adjust to SG compensation values
 168  *  - send an event to the client SM
 169  *
 170  * \sa  scanCncn_StopScan
 171  */
 172 EScanCncnResultStatus   scanCncn_Start1ShotScan (TI_HANDLE hScanCncn, EScanCncnClient eClient, TScanParams* pScanParams);
 173 /**
 174  * \brief Stop an on-going one-shot scan operation
 175  *
 176  * \param  hScanCncn    - Handle to the scan concentrator object
 177  * \param  eClient              - The client requesting to stop the scan operation
 178  * \return void
 179  *
 180  * \par Description
 181  * Set necessary flags and send a stop scan event to the client SM
 182  *
 183  * \sa  scanCncn_Start1ShotScan
 184  */
 185 void                    scanCncn_StopScan (TI_HANDLE hScanCncn, EScanCncnClient eClient);
 186 EScanCncnResultStatus   scanCncn_StartPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient,
 187                                                     TPeriodicScanParams *pScanParams);
 188 void                    scanCncn_StopPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient);
 189 /**
 190  * \brief Registers a scan complete object
 191  *
 192  * \param  hScanCncn            - Handle to the scan concentrator object
 193  * \param  eClient                      - The client requesting to stop the scan operation
 194  * \param  scanResultCBFunc - Pointer to the resulting callback function
 195  * \param  scanResultCBObj      - Object passed to the scan resulting callback function
 196  * \return void
 197  *
 198  * \par Description
 199  * Registers a callback function for a client that is called for every scan result and scan complete event.
 200  * It is called by each client one time before issuing a scan request.
 201  *
 202  * \sa
 203  */
 204 void                    scanCncn_RegisterScanResultCB (TI_HANDLE hScanCncn, EScanCncnClient eClient,
 205                                                        TScanResultCB scanResultCBFunc, TI_HANDLE scanResultCBObj);
 206 void                    scanCncn_ScanCompleteNotificationCB (TI_HANDLE hScanCncn, EScanResultTag eTag,
 207                                                              TI_UINT32 uResultCount, TI_UINT16 SPSStatus,
 208                                                              TI_BOOL bTSFError, TI_STATUS scanStatus,
 209                                                              TI_STATUS PSMode);
 210 void                    scanCncn_MlmeResultCB (TI_HANDLE hScanCncn, TMacAddr* bssid, mlmeFrameInfo_t* frameInfo,
 211                                                TRxAttr* pRxAttr, TI_UINT8* buffer, TI_UINT16 bufferLength);
 212 void                    scanCncn_ScrRoamingImmedCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
 213                                                     EScrResourceId eResource, EScePendReason ePendReason);
 214 void                    scanCncn_ScrRoamingContCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
 215                                                    EScrResourceId eResource, EScePendReason ePendReason);
 216 void                    scanCncn_ScrAppCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
 217                                            EScrResourceId eResource, EScePendReason ePendReason );
 218 void                    scanCncn_ScrDriverCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
 219                                               EScrResourceId eResource, EScePendReason ePendReason);
 220 void                    scanCncn_SGconfigureScanParams (TI_HANDLE hScanCncn, TI_BOOL bUseSGParams,
 221                                                         TI_UINT8 probeReqPercent, TI_UINT32 SGcompensationMaxTime,
 222                                                         TI_UINT32 SGcompensationPercent);
 223 /* Scan concentrator application functions */
 224 TI_STATUS               scanCncnApp_SetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam);
 225 TI_STATUS               scanCncnApp_GetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam);
 226 void                    scanCncn_AppScanResultCB (TI_HANDLE hScanCncn, EScanCncnResultStatus status,
 227                                                   TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus);
 228 void                    scanCncn_PeriodicScanCompleteCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen);
 229 void                    scanCncn_PeriodicScanReportCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen);
 230
 231 #endif /* __SCANCNCN_H__ */
 232