Mistake on this page?
Report an issue in GitHub or email us
whd_events.h
Go to the documentation of this file.
1 /*
2  * Copyright 2020 Cypress Semiconductor Corporation
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 
55 /* List of status codes - Applicable for any event type */
56 #define WLC_E_STATUS_SUCCESS 0 /**< operation was successful */
57 #define WLC_E_STATUS_FAIL 1 /**< operation failed */
58 #define WLC_E_STATUS_TIMEOUT 2 /**< operation timed out */
59 #define WLC_E_STATUS_NO_NETWORKS 3 /**< failed due to no matching network found */
60 #define WLC_E_STATUS_ABORT 4 /**< operation was aborted */
61 #define WLC_E_STATUS_NO_ACK 5 /**< protocol failure: packet not ack'd */
62 #define WLC_E_STATUS_UNSOLICITED 6 /**< AUTH or ASSOC packet was unsolicited */
63 #define WLC_E_STATUS_ATTEMPT 7 /**< attempt to assoc to an auto auth configuration */
64 #define WLC_E_STATUS_PARTIAL 8 /**< scan results are incomplete */
65 #define WLC_E_STATUS_NEWSCAN 9 /**< scan aborted by another scan */
66 #define WLC_E_STATUS_NEWASSOC 10 /**< scan aborted due to assoc in progress */
67 #define WLC_E_STATUS_11HQUIET 11 /**< 802.11h quiet period started */
68 #define WLC_E_STATUS_SUPPRESS 12 /**< user disabled scanning (WLC_SET_SCANSUPPRESS) */
69 #define WLC_E_STATUS_NOCHANS 13 /**< no allowable channels to scan */
70 #define WLC_E_STATUS_CCXFASTRM 14 /**< scan aborted due to CCX fast roam */
71 #define WLC_E_STATUS_CS_ABORT 15 /**< abort channel select */
72 #define WLC_E_STATUS_ERROR 16 /**< request failed due to error */
73 #define WLC_E_STATUS_INVALID 0xff /**< Invalid status code to init variables. */
74 
75 #define WLC_SUP_STATUS_OFFSET (256) /**< Status offset added to the status codes to match the values from firmware. */
76 
77 /**
78  * @brief Status code for event WLC_E_PSK_SUP
79  *
80  * -Basic supplicant authentication states
81  *
82  + WLC_SUP_DISCONNECTED
83  * + WLC_SUP_CONNECTING
84  * + WLC_SUP_IDREQUIRED
85  * + WLC_SUP_AUTHENTICATING
86  * + WLC_SUP_AUTHENTICATED
87  * + WLC_SUP_KEYXCHANGE
88  * + WLC_SUP_KEYED
89  * + WLC_SUP_TIMEOUT
90  * + WLC_SUP_LAST_BASIC_STATE
91  * -Extended supplicant authentication states
92  * + WLC_SUP_KEYXCHANGE_WAIT_M1
93  * + WLC_SUP_KEYXCHANGE_PREP_M2
94  * + WLC_SUP_KEYXCHANGE_WAIT_M3
95  * + WLC_SUP_KEYXCHANGE_PREP_M4
96  * + WLC_SUP_KEYXCHANGE_WAIT_G1
97  * + WLC_SUP_KEYXCHANGE_PREP_G2
98  */
99 typedef enum sup_auth_status
100 {
101  WLC_SUP_DISCONNECTED = 0 + WLC_SUP_STATUS_OFFSET, /**< Disconnected */
102  WLC_SUP_CONNECTING = 1 + WLC_SUP_STATUS_OFFSET, /**< Connecting */
103  WLC_SUP_IDREQUIRED = 2 + WLC_SUP_STATUS_OFFSET, /**< ID Required */
104  WLC_SUP_AUTHENTICATING = 3 + WLC_SUP_STATUS_OFFSET, /**< Authenticating */
105  WLC_SUP_AUTHENTICATED = 4 + WLC_SUP_STATUS_OFFSET, /**< Authenticated */
106  WLC_SUP_KEYXCHANGE = 5 + WLC_SUP_STATUS_OFFSET, /**< Key Exchange */
107  WLC_SUP_KEYED = 6 + WLC_SUP_STATUS_OFFSET, /**< Key Exchanged */
108  WLC_SUP_TIMEOUT = 7 + WLC_SUP_STATUS_OFFSET, /**< Timeout */
109  WLC_SUP_LAST_BASIC_STATE = 8 + WLC_SUP_STATUS_OFFSET, /**< Last Basic State */
110  WLC_SUP_KEYXCHANGE_WAIT_M1 = WLC_SUP_AUTHENTICATED, /**< Waiting to receive handshake msg M1 */
111  WLC_SUP_KEYXCHANGE_PREP_M2 = WLC_SUP_KEYXCHANGE, /**< Preparing to send handshake msg M2 */
112  WLC_SUP_KEYXCHANGE_WAIT_M3 = WLC_SUP_LAST_BASIC_STATE, /**< Waiting to receive handshake msg M3 */
113  WLC_SUP_KEYXCHANGE_PREP_M4 = 9 + WLC_SUP_STATUS_OFFSET, /**< Preparing to send handshake msg M4 */
114  WLC_SUP_KEYXCHANGE_WAIT_G1 = 10 + WLC_SUP_STATUS_OFFSET, /**< Waiting to receive handshake msg G1 */
115  WLC_SUP_KEYXCHANGE_PREP_G2 = 11 + WLC_SUP_STATUS_OFFSET /**< Preparing to send handshake msg G2 */
117 
118 #define WHD_MSG_IFNAME_MAX 16 /**< Max length of Interface name */
120 #pragma pack(1)
121 
122 /**
123  * Structure to store ethernet header fields in event packets
124  */
125 typedef struct whd_event_eth_hdr
126 {
127  uint16_t subtype; /**< Vendor specific..32769 */
128  uint16_t length; /**< Length of ethernet header*/
129  uint8_t version; /**< Version is 0 */
130  uint8_t oui[3]; /**< Organizationally Unique Identifier */
131  uint16_t usr_subtype; /**< User specific data */
133 
134 /**
135  * Structure to store ethernet destination, source and ethertype in event packets
136  */
137 typedef struct whd_event_ether_header
138 {
139  whd_mac_t destination_address; /**< Ethernet destination address */
140  whd_mac_t source_address; /**< Ethernet source address */
141  uint16_t ethertype; /**< Ethertype for identifying event packets */
143 
144 /**
145  * Structure to store fields after ethernet header in event message
146  */
147 struct whd_event_msg
148 {
149  uint16_t version; /**< Version */
150  uint16_t flags; /**< see flags below */
151  uint32_t event_type; /**< Event type indicating a response from firmware for IOCTLs/IOVARs sent */
152  uint32_t status; /**< Status code corresponding to any event type */
153  uint32_t reason; /**< Reason code associated with the event occurred */
154  uint32_t auth_type; /**< WLC_E_AUTH: 802.11 AUTH request */
155  uint32_t datalen; /**< Length of data in event message */
156  whd_mac_t addr; /**< Station address (if applicable) */
157  char ifname[WHD_MSG_IFNAME_MAX]; /**< name of the incoming packet interface */
158  uint8_t ifidx; /**< destination OS i/f index */
159  uint8_t bsscfgidx; /**< source bsscfg index */
160 };
161 
162 /**
163  * Event structure used by driver msgs
164  */
165 typedef struct whd_event
166 {
167  whd_event_ether_header_t eth; /**< Variable to store ethernet destination, source and ethertype in event packets */
168  whd_event_eth_hdr_t eth_evt_hdr; /**< Variable to store ethernet header fields in event message */
169  whd_event_header_t whd_event; /**< Variable to store rest of the event packet fields after ethernet header */
170  /* data portion follows */
171 } whd_event_t;
172 
173 #pragma pack()
174 
175 /** @addtogroup event WHD Event handling API
176  * Functions that allow user applications to receive event callbacks and set event handlers
177  * @{
178  */
179 /** Event handler prototype definition
180  *
181  * @param ifp Pointer to handle instance of whd interface
182  * @param event_header whd event header
183  * @param event_data event data
184  * @param handler_user_data semaphore data
185  */
186 typedef void *(*whd_event_handler_t)(whd_interface_t ifp, const whd_event_header_t *event_header,
187  const uint8_t *event_data, void *handler_user_data);
188 
189 /** Registers a handler to receive event callbacks.
190  *
191  * This function registers a callback handler to be notified when
192  * a particular event is received.
193  *
194  *
195  * @note Currently each event may only be registered to one handler and there is a limit to the number of simultaneously
196  * registered events. Maximum of 5 event handlers can registered simultaneously, this also includes the internal
197  * event handler registration which happens during scan, join and starting an AP.
198  *
199  * @param ifp Pointer to handle instance of whd interface
200  * @param event_type Pointer to the event list array
201  * @param handler_func A function pointer to the handler callback
202  * @param handler_user_data A pointer value which will be passed to the event handler function
203  * at the time an event is triggered (NULL is allowed)
204  * @param event_index Entry where the event handler is registered in the list
205  *
206  * @return WHD_SUCCESS or Error code
207  */
208 uint32_t whd_wifi_set_event_handler(whd_interface_t ifp, const uint32_t *event_type, whd_event_handler_t handler_func,
209  void *handler_user_data, uint16_t *event_index);
210 /* @} */
211 
212 /** Delete/Deregister the event entry where callback is registered
213  *
214  * @param ifp Pointer to handle instance of whd interface
215  * @param event_index Event index obtained during registration by whd_wifi_set_event_handler
216  *
217  * @return WHD_SUCCESS or Error code
218  */
219 
220 uint32_t whd_wifi_deregister_event_handler(whd_interface_t ifp, uint16_t event_index);
221 
222 #ifdef __cplusplus
223 } /* extern "C" */
224 #endif
225 #endif /* ifndef */
226 
sup_auth_status
Status code for event WLC_E_PSK_SUP.
Definition: whd_events.h:100
void *(* whd_event_handler_t)(whd_interface_t ifp, const whd_event_header_t *event_header, const uint8_t *event_data, void *handler_user_data)
Event handler prototype definition.
Definition: whd_events.h:187
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:116
uint8_t oui[3]
Organizationally Unique Identifier.
Definition: whd_events.h:131
uint16_t usr_subtype
User specific data.
Definition: whd_events.h:132
struct whd_event_eth_hdr whd_event_eth_hdr_t
Structure to store ethernet header fields in event packets.
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:102
Provides abstract pointer type to act as instance for: driver, interface, buffer funcs, network funcs, resource funcs and bus funcs.
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:107
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:103
Preparing to send handshake msg M2.
Definition: whd_events.h:112
struct whd_event_ether_header whd_event_ether_header_t
Structure to store ethernet destination, source and ethertype in event packets.
uint32_t whd_wifi_set_event_handler(whd_interface_t ifp, const uint32_t *event_type, whd_event_handler_t handler_func, void *handler_user_data, uint16_t *event_index)
Registers a handler to receive event callbacks.
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:109
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:108
Event structure used by driver msgs.
Definition: whd_events.h:166
uint16_t length
Length of ethernet header.
Definition: whd_events.h:129
uint16_t subtype
Vendor specific..32769.
Definition: whd_events.h:128
Waiting to receive handshake msg M1.
Definition: whd_events.h:111
Structure for storing a MAC address (Wi-Fi Media Access Control address).
Definition: whd_types.h:385
Structure to store fields after ethernet header in event message.
Definition: whd_events.h:148
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:110
struct whd_event whd_event_t
Event structure used by driver msgs.
Structure to store ethernet destination, source and ethertype in event packets.
Definition: whd_events.h:138
Structure to store ethernet header fields in event packets.
Definition: whd_events.h:126
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:114
#define WLC_SUP_STATUS_OFFSET
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:76
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:106
uint32_t whd_wifi_deregister_event_handler(whd_interface_t ifp, uint16_t event_index)
Delete/Deregister the event entry where callback is registered.
#define WHD_MSG_IFNAME_MAX
Max length of Interface name.
Definition: whd_events.h:119
enum sup_auth_status sup_auth_status_t
Status code for event WLC_E_PSK_SUP.
Waiting to receive handshake msg M3.
Definition: whd_events.h:113
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:115
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:105
uint8_t version
Version is 0.
Definition: whd_events.h:130
Status offset added to the status codes to match the values from firmware.
Definition: whd_events.h:104
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.