1 /* 2 * Copyright 2023, Cypress Semiconductor Corporation (an Infineon company) 3 * SPDX-License-Identifier: Apache-2.0 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** @file whd_events.h 19 * Header for Event detection 20 * 21 * Provides constants and prototypes for functions that allow 22 * user applications to receive event callbacks and set event handlers 23 */ 24 #ifndef INCLUDED_WHD_EVENTS_API_H 25 #define INCLUDED_WHD_EVENTS_API_H 26 27 #include "whd.h" 28 29 #ifdef __cplusplus 30 extern "C" 31 { 32 #endif 33 34 /* List of events */ 35 #define WLC_E_NONE (0x7FFFFFFE) /**< Indicates the end of the event array list */ 36 37 #define WLC_E_SET_SSID 0 /**< Indicates status of set SSID. This event occurs when STA tries to join the AP*/ 38 #define WLC_E_AUTH 3 /**< 802.11 AUTH request event occurs when STA tries to get authenticated with the AP */ 39 #define WLC_E_DEAUTH 5 /**< 802.11 DEAUTH request event occurs when the the SOFTAP is stopped to deuthenticate the connected stations*/ 40 #define WLC_E_DEAUTH_IND 6 /**< 802.11 DEAUTH indication event occurs when the STA gets deauthenticated by the AP */ 41 #define WLC_E_ASSOC 7 /**< 802.11 ASSOC request event occurs when STA joins the AP */ 42 #define WLC_E_ASSOC_IND 8 /**< 802.11 ASSOC indication occurs when a station joins the SOFTAP that is started */ 43 #define WLC_E_REASSOC 9 /**< 802.11 REASSOC request event when the STA again gets associated with the AP */ 44 #define WLC_E_REASSOC_IND 10 /**< 802.11 REASSOC indication occurs when a station again reassociates with the SOFTAP*/ 45 #define WLC_E_DISASSOC 11 /**< 802.11 DISASSOC request occurs when the STA the tries to leave the AP*/ 46 #define WLC_E_DISASSOC_IND 12 /**< 802.11 DISASSOC indication occurs when the connected station gets disassociates from SOFTAP, 47 also when STA gets diassociated by the AP*/ 48 #define WLC_E_LINK 16 /**< generic link indication */ 49 #define WLC_E_PROBREQ_MSG 44 /**< Indicates probe request received for the SOFTAP started*/ 50 #define WLC_E_PSK_SUP 46 /**< WPA Handshake fail during association*/ 51 #define WLC_E_ACTION_FRAME 59 /**< Indicates Action frame Rx */ 52 #define WLC_E_ACTION_FRAME_COMPLETE 60 /**< Indicates Action frame Tx complete */ 53 #define WLC_E_ESCAN_RESULT 69 /**< escan result event occurs when we scan for the networks */ 54 #define WLC_E_EXT_AUTH_REQ 187 /**< authentication request received */ 55 #define WLC_E_EXT_AUTH_FRAME_RX 188 /**< authentication request received */ 56 #define WLC_E_MGMT_FRAME_TXSTATUS 189 /**< mgmt frame Tx complete */ 57 58 /* List of status codes - Applicable for any event type */ 59 #define WLC_E_STATUS_SUCCESS 0 /**< operation was successful */ 60 #define WLC_E_STATUS_FAIL 1 /**< operation failed */ 61 #define WLC_E_STATUS_TIMEOUT 2 /**< operation timed out */ 62 #define WLC_E_STATUS_NO_NETWORKS 3 /**< failed due to no matching network found */ 63 #define WLC_E_STATUS_ABORT 4 /**< operation was aborted */ 64 #define WLC_E_STATUS_NO_ACK 5 /**< protocol failure: packet not ack'd */ 65 #define WLC_E_STATUS_UNSOLICITED 6 /**< AUTH or ASSOC packet was unsolicited */ 66 #define WLC_E_STATUS_ATTEMPT 7 /**< attempt to assoc to an auto auth configuration */ 67 #define WLC_E_STATUS_PARTIAL 8 /**< scan results are incomplete */ 68 #define WLC_E_STATUS_NEWSCAN 9 /**< scan aborted by another scan */ 69 #define WLC_E_STATUS_NEWASSOC 10 /**< scan aborted due to assoc in progress */ 70 #define WLC_E_STATUS_11HQUIET 11 /**< 802.11h quiet period started */ 71 #define WLC_E_STATUS_SUPPRESS 12 /**< user disabled scanning (WLC_SET_SCANSUPPRESS) */ 72 #define WLC_E_STATUS_NOCHANS 13 /**< no allowable channels to scan */ 73 #define WLC_E_STATUS_CCXFASTRM 14 /**< scan aborted due to CCX fast roam */ 74 #define WLC_E_STATUS_CS_ABORT 15 /**< abort channel select */ 75 #define WLC_E_STATUS_ERROR 16 /**< request failed due to error */ 76 #define WLC_E_STATUS_INVALID 0xff /**< Invalid status code to init variables. */ 77 78 #define WLC_SUP_STATUS_OFFSET (256) /**< Status offset added to the status codes to match the values from firmware. */ 79 80 /** 81 * @brief Status code for event WLC_E_PSK_SUP 82 * 83 * -Basic supplicant authentication states 84 * 85 * + WLC_SUP_DISCONNECTED 86 * + WLC_SUP_CONNECTING 87 * + WLC_SUP_IDREQUIRED 88 * + WLC_SUP_AUTHENTICATING 89 * + WLC_SUP_AUTHENTICATED 90 * + WLC_SUP_KEYXCHANGE 91 * + WLC_SUP_KEYED 92 * + WLC_SUP_TIMEOUT 93 * + WLC_SUP_LAST_BASIC_STATE 94 * 95 * -Extended supplicant authentication states 96 * 97 * + WLC_SUP_KEYXCHANGE_WAIT_M1 98 * + WLC_SUP_KEYXCHANGE_PREP_M2 99 * + WLC_SUP_KEYXCHANGE_WAIT_M3 100 * + WLC_SUP_KEYXCHANGE_PREP_M4 101 * + WLC_SUP_KEYXCHANGE_WAIT_G1 102 * + WLC_SUP_KEYXCHANGE_PREP_G2 103 */ 104 typedef enum sup_auth_status 105 { 106 WLC_SUP_DISCONNECTED = 0 + WLC_SUP_STATUS_OFFSET, /**< Disconnected */ 107 WLC_SUP_CONNECTING = 1 + WLC_SUP_STATUS_OFFSET, /**< Connecting */ 108 WLC_SUP_IDREQUIRED = 2 + WLC_SUP_STATUS_OFFSET, /**< ID Required */ 109 WLC_SUP_AUTHENTICATING = 3 + WLC_SUP_STATUS_OFFSET, /**< Authenticating */ 110 WLC_SUP_AUTHENTICATED = 4 + WLC_SUP_STATUS_OFFSET, /**< Authenticated */ 111 WLC_SUP_KEYXCHANGE = 5 + WLC_SUP_STATUS_OFFSET, /**< Key Exchange */ 112 WLC_SUP_KEYED = 6 + WLC_SUP_STATUS_OFFSET, /**< Key Exchanged */ 113 WLC_SUP_TIMEOUT = 7 + WLC_SUP_STATUS_OFFSET, /**< Timeout */ 114 WLC_SUP_LAST_BASIC_STATE = 8 + WLC_SUP_STATUS_OFFSET, /**< Last Basic State */ 115 WLC_SUP_KEYXCHANGE_WAIT_M1 = WLC_SUP_AUTHENTICATED, /**< Waiting to receive handshake msg M1 */ 116 WLC_SUP_KEYXCHANGE_PREP_M2 = WLC_SUP_KEYXCHANGE, /**< Preparing to send handshake msg M2 */ 117 WLC_SUP_KEYXCHANGE_WAIT_M3 = WLC_SUP_LAST_BASIC_STATE, /**< Waiting to receive handshake msg M3 */ 118 WLC_SUP_KEYXCHANGE_PREP_M4 = 9 + WLC_SUP_STATUS_OFFSET, /**< Preparing to send handshake msg M4 */ 119 WLC_SUP_KEYXCHANGE_WAIT_G1 = 10 + WLC_SUP_STATUS_OFFSET, /**< Waiting to receive handshake msg G1 */ 120 WLC_SUP_KEYXCHANGE_PREP_G2 = 11 + WLC_SUP_STATUS_OFFSET /**< Preparing to send handshake msg G2 */ 121 } sup_auth_status_t; 122 123 #define WHD_MSG_IFNAME_MAX 16 /**< Max length of Interface name */ 124 125 /* Reason codes for LINK */ 126 #define WLC_E_LINK_BCN_LOSS 1 /**< Link down because of beacon loss */ 127 #define WLC_E_LINK_DISASSOC 2 /**< Link down because of disassoc */ 128 #define WLC_E_LINK_ASSOC_REC 3 /**< Link down because assoc recreate failed */ 129 #define WLC_E_LINK_BSSCFG_DIS 4 /**< Link down due to bsscfg down */ 130 131 #pragma pack(1) 132 133 /** 134 * Structure to store ethernet header fields in event packets 135 */ 136 typedef struct whd_event_eth_hdr 137 { 138 uint16_t subtype; /**< Vendor specific..32769 */ 139 uint16_t length; /**< Length of ethernet header*/ 140 uint8_t version; /**< Version is 0 */ 141 uint8_t oui[3]; /**< Organizationally Unique Identifier */ 142 uint16_t usr_subtype; /**< User specific data */ 143 } whd_event_eth_hdr_t; 144 145 /** 146 * Structure to store ethernet destination, source and ethertype in event packets 147 */ 148 typedef struct whd_event_ether_header 149 { 150 whd_mac_t destination_address; /**< Ethernet destination address */ 151 whd_mac_t source_address; /**< Ethernet source address */ 152 uint16_t ethertype; /**< Ethertype for identifying event packets */ 153 } whd_event_ether_header_t; 154 155 /** 156 * Structure to store fields after ethernet header in event message 157 */ 158 struct whd_event_msg 159 { 160 uint16_t version; /**< Version */ 161 uint16_t flags; /**< see flags below */ 162 uint32_t event_type; /**< Event type indicating a response from firmware for IOCTLs/IOVARs sent */ 163 uint32_t status; /**< Status code corresponding to any event type */ 164 uint32_t reason; /**< Reason code associated with the event occurred */ 165 uint32_t auth_type; /**< WLC_E_AUTH: 802.11 AUTH request */ 166 uint32_t datalen; /**< Length of data in event message */ 167 whd_mac_t addr; /**< Station address (if applicable) */ 168 char ifname[WHD_MSG_IFNAME_MAX]; /**< name of the incoming packet interface */ 169 uint8_t ifidx; /**< destination OS i/f index */ 170 uint8_t bsscfgidx; /**< source bsscfg index */ 171 }; 172 173 /** 174 * Event structure used by driver msgs 175 */ 176 typedef struct whd_event 177 { 178 whd_event_ether_header_t eth; /**< Variable to store ethernet destination, source and ethertype in event packets */ 179 whd_event_eth_hdr_t eth_evt_hdr; /**< Variable to store ethernet header fields in event message */ 180 whd_event_header_t whd_event; /**< Variable to store rest of the event packet fields after ethernet header */ 181 /* data portion follows */ 182 } whd_event_t; 183 184 #pragma pack() 185 186 /** @addtogroup event WHD Event handling API 187 * Functions that allow user applications to receive event callbacks and set event handlers 188 * @{ 189 */ 190 /** Event handler prototype definition 191 * 192 * @param ifp Pointer to handle instance of whd interface 193 * @param event_header whd event header 194 * @param event_data event data 195 * @param handler_user_data semaphore data 196 */ 197 typedef void *(*whd_event_handler_t)(whd_interface_t ifp, const whd_event_header_t *event_header, 198 const uint8_t *event_data, void *handler_user_data); 199 /** Error handler prototype definition 200 * 201 * @param whd_driver Pointer to handle instance of whd driver 202 * @param error_type whd error type 203 * @param event_data event data 204 * @param handler_user_data semaphore data 205 */ 206 typedef void *(*whd_error_handler_t)(whd_driver_t whd_driver, const uint8_t *error_type, 207 const uint8_t *event_data, void *handler_user_data); 208 /* @} */ 209 /** Registers a handler to receive event callbacks. 210 * 211 * This function registers a callback handler to be notified when 212 * a particular event is received. 213 * 214 * 215 * @note Currently each event may only be registered to one handler and there is a limit to the number of simultaneously 216 * registered events. Maximum of 5 event handlers can registered simultaneously, this also includes the internal 217 * event handler registration which happens during scan, join and starting an AP. 218 * 219 * @param ifp Pointer to handle instance of whd interface 220 * @param event_type Pointer to the event list array 221 * @param handler_func A function pointer to the handler callback 222 * @param handler_user_data A pointer value which will be passed to the event handler function 223 * at the time an event is triggered (NULL is allowed) 224 * @param event_index Entry where the event handler is registered in the list 225 * 226 * @return WHD_SUCCESS or Error code 227 */ 228 uint32_t whd_wifi_set_event_handler(whd_interface_t ifp, const uint32_t *event_type, whd_event_handler_t handler_func, 229 void *handler_user_data, uint16_t *event_index); 230 /** Registers a handler to receive error callbacks. 231 * 232 * This function registers a callback handler to be notified when 233 * a particular event is received. 234 * 235 * 236 * @note Currently each event may only be registered to one handler and there is a limit to the number of simultaneously 237 * registered events. Maximum of 5 event handlers can registered simultaneously, this also includes the internal 238 * event handler registration which happens during scan, join and starting an AP. 239 * 240 * @param ifp Pointer to handle instance of whd interface 241 * @param error_nums Pointer to the event list as WLC_ERR_BUS and WLC_ERR_FW 242 * @param handler_func A function pointer to the handler callback 243 * @param handler_user_data A pointer value which will be passed to the event handler function 244 * at the time an event is triggered (NULL is allowed) 245 * @param error_index Entry where the error handler is registered in the list 246 * 247 * @return WHD_SUCCESS or Error code 248 */ 249 uint32_t whd_wifi_set_error_handler(whd_interface_t ifp, const uint8_t *error_nums, whd_error_handler_t handler_func, 250 void *handler_user_data, uint16_t *error_index); 251 252 /** Delete/Deregister the event entry where callback is registered 253 * 254 * @param ifp Pointer to handle instance of whd interface 255 * @param event_index Event index obtained during registration by whd_wifi_set_event_handler 256 * 257 * @return WHD_SUCCESS or Error code 258 */ 259 260 uint32_t whd_wifi_deregister_event_handler(whd_interface_t ifp, uint16_t event_index); 261 /** Delete/Deregister the error entry where callback is registered 262 * 263 * @param ifp Pointer to handle instance of whd interface 264 * @param error_index Error index obtained during registration by whd_wifi_set_error_handler 265 * 266 * @return WHD_SUCCESS or Error code 267 */ 268 269 uint32_t whd_wifi_deregister_error_handler(whd_interface_t ifp, uint16_t error_index); 270 271 #ifdef __cplusplus 272 } /* extern "C" */ 273 #endif 274 #endif /* ifndef */ 275 276
