1/*
2 * FST module - interface definitions
3 * Copyright (c) 2014, Qualcomm Atheros, Inc.
4 *
5 * This software may be distributed under the terms of the BSD license.
6 * See README for more details.
7 */
8
9#ifndef FST_H
10#define FST_H
11
12#ifdef CONFIG_FST
13
14#include "common/defs.h"
15#include "fst/fst_ctrl_iface.h"
16
17/* FST module hostap integration API */
18
19#define US_IN_MS           1000
20#define LLT_UNIT_US        32 /* See 10.32.2.2  Transitioning between states */
21
22/*
23 * These were originally
24 * #define FST_LLT_MS_TO_VAL(m) (((u32) (m)) * US_IN_MS / LLT_UNIT_US)
25 * #define FST_LLT_VAL_TO_MS(v) (((u32) (v)) * LLT_UNIT_US / US_IN_MS)
26 * #define FST_MAX_LLT_MS FST_LLT_VAL_TO_MS(-1)
27 * but those can overflow 32-bit unsigned integer, so use alternative defines
28 * to avoid undefined behavior with such overflow.
29 * LLT_UNIT_US/US_IN_MS = 32/1000 = 4/125
30 */
31#define FST_LLT_MS_TO_VAL(m) (((u32) (m)) * 125 / 4)
32#define FST_LLT_VAL_TO_MS(v) (((u32) (v)) * 4 / 125)
33#define FST_MAX_LLT_MS       (((u32) -1) / 4)
34#define FST_MAX_PRIO_VALUE   ((u8) -1)
35#define FST_MAX_GROUP_ID_LEN IFNAMSIZ
36
37#define FST_DEFAULT_LLT_CFG_VALUE 50
38
39struct hostapd_hw_modes;
40struct ieee80211_mgmt;
41struct fst_iface;
42struct fst_group;
43struct fst_session;
44struct fst_get_peer_ctx;
45struct fst_ctrl_handle;
46
47struct fst_wpa_obj {
48	void *ctx;
49
50	/**
51	 * get_bssid - Get BSSID of the interface
52	 * @ctx: User context %ctx
53	 * Returns: BSSID for success, %NULL for failure.
54	 *
55	 * NOTE: For AP it returns the own BSSID, while for STA - the BSSID of
56	 * the associated AP.
57	 */
58	const u8 * (*get_bssid)(void *ctx);
59
60	/**
61	 * get_channel_info - Get current channel info
62	 * @ctx: User context %ctx
63	 * @hw_mode: OUT, current HW mode
64	 * @channel: OUT, current channel
65	 */
66	void (*get_channel_info)(void *ctx, enum hostapd_hw_mode *hw_mode,
67				 u8 *channel);
68
69	/**
70	 * get_hw_modes - Get hardware modes
71	 * @ctx: User context %ctx
72	 * @modes: OUT, pointer on array of hw modes
73	 *
74	 * Returns: Number of hw modes available.
75	 */
76	int (*get_hw_modes)(void *ctx, struct hostapd_hw_modes **modes);
77
78	/**
79	 * set_ies - Set interface's MB IE
80	 * @ctx: User context %ctx
81	 * @fst_ies: MB IE buffer (owned by FST module)
82	 */
83	void (*set_ies)(void *ctx, const struct wpabuf *fst_ies);
84
85	/**
86	 * send_action - Send FST Action frame via the interface
87	 * @ctx: User context %ctx
88	 * @addr: Address of the destination STA
89	 * @data: Action frame buffer
90	 * Returns: 0 for success, negative error code for failure.
91	 */
92	int (*send_action)(void *ctx, const u8 *addr, struct wpabuf *data);
93
94	/**
95	 * get_mb_ie - Get last MB IE received from STA
96	 * @ctx: User context %ctx
97	 * @addr: Address of the STA
98	 * Returns: MB IE buffer, %NULL if no MB IE received from the STA
99	 */
100	const struct wpabuf * (*get_mb_ie)(void *ctx, const u8 *addr);
101
102	/**
103	 * update_mb_ie - Update last MB IE received from STA
104	 * @ctx: User context %ctx
105	 * @addr: Address of the STA
106	 * @buf: Buffer that contains the MB IEs data
107	 * @size: Size of data in %buf
108	 */
109	void (*update_mb_ie)(void *ctx, const u8 *addr,
110			     const u8 *buf, size_t size);
111
112	/**
113	 * get_peer_first - Get MAC address of the 1st connected STA
114	 * @ctx: User context %ctx
115	 * @get_ctx: Context to be used for %get_peer_next call
116	 * @mb_only: %true if only multi-band capable peer should be reported
117	 * Returns: Address of the 1st connected STA, %NULL if no STAs connected
118	 */
119	const u8 * (*get_peer_first)(void *ctx,
120				     struct fst_get_peer_ctx **get_ctx,
121				     bool mb_only);
122	/**
123	 * get_peer_next - Get MAC address of the next connected STA
124	 * @ctx: User context %ctx
125	 * @get_ctx: Context received from %get_peer_first or previous
126	 *           %get_peer_next call
127	 * @mb_only: %true if only multi-band capable peer should be reported
128	 * Returns: Address of the next connected STA, %NULL if no more STAs
129	 *          connected
130	 */
131	const u8 * (*get_peer_next)(void *ctx,
132				    struct fst_get_peer_ctx **get_ctx,
133				    bool mb_only);
134};
135
136/**
137 * fst_global_init - Global FST module initiator
138 * Returns: 0 for success, negative error code for failure.
139 * Note: The purpose of this function is to allocate and initiate global
140 *       FST module data structures (linked lists, static data etc.)
141 *       This function should be called prior to the 1st %fst_attach call.
142 */
143int fst_global_init(void);
144
145/**
146 * fst_global_deinit - Global FST module de-initiator
147 * Note: The purpose of this function is to deallocate and de-initiate global
148 *       FST module data structures (linked lists, static data etc.)
149 */
150void fst_global_deinit(void);
151
152/**
153 * struct fst_ctrl - Notification interface for FST module
154 */
155struct fst_ctrl {
156	/**
157	 * init - Initialize the notification interface
158	 * Returns: 0 for success, negative error code for failure.
159	 */
160	int (*init)(void);
161
162	/**
163	 * deinit - Deinitialize the notification interface
164	 */
165	void (*deinit)(void);
166
167	/**
168	 * on_group_created - Notify about FST group creation
169	 * Returns: 0 for success, negative error code for failure.
170	 */
171	int (*on_group_created)(struct fst_group *g);
172
173	/**
174	 * on_group_deleted - Notify about FST group deletion
175	 */
176	void (*on_group_deleted)(struct fst_group *g);
177
178	/**
179	 * on_iface_added - Notify about interface addition
180	 * Returns: 0 for success, negative error code for failure.
181	 */
182	int (*on_iface_added)(struct fst_iface *i);
183
184	/**
185	 * on_iface_removed - Notify about interface removal
186	 */
187	void (*on_iface_removed)(struct fst_iface *i);
188
189	/**
190	 * on_session_added - Notify about FST session addition
191	 * Returns: 0 for success, negative error code for failure.
192	 */
193	int (*on_session_added)(struct fst_session *s);
194
195	/**
196	 * on_session_removed - Notify about FST session removal
197	 */
198	void (*on_session_removed)(struct fst_session *s);
199
200	/**
201	 * on_event - Notify about FST event
202	 * @event_type: Event type
203	 * @i: Interface object that relates to the event or NULL
204	 * @g: Group object that relates to the event or NULL
205	 * @extra - Event specific data (see fst_ctrl_iface.h for more info)
206	 */
207	void (*on_event)(enum fst_event_type event_type, struct fst_iface *i,
208			 struct fst_session *s,
209			 const union fst_event_extra *extra);
210};
211
212struct fst_ctrl_handle * fst_global_add_ctrl(const struct fst_ctrl *ctrl);
213void fst_global_del_ctrl(struct fst_ctrl_handle *h);
214
215/**
216 * NOTE: These values have to be read from configuration file
217 */
218struct fst_iface_cfg {
219	char group_id[FST_MAX_GROUP_ID_LEN + 1];
220	u8 priority;
221	u32 llt;
222};
223
224/**
225 * fst_attach - Attach interface to an FST group according to configuration read
226 * @ifname: Interface name
227 * @own_addr: Own interface MAC address
228 * @iface_obj: Callbacks to be used by FST module to communicate with
229 *             hostapd/wpa_supplicant
230 * @cfg: FST-related interface configuration read from the configuration file
231 * Returns: FST interface object for success, %NULL for failure.
232 */
233struct fst_iface * fst_attach(const char *ifname,
234			      const u8 *own_addr,
235			      const struct fst_wpa_obj *iface_obj,
236			      const struct fst_iface_cfg *cfg);
237
238/**
239 * fst_detach - Detach an interface
240 * @iface: FST interface object
241 */
242void fst_detach(struct fst_iface *iface);
243
244/* FST module inputs */
245/**
246 * fst_rx_action - FST Action frames handler
247 * @iface: FST interface object
248 * @mgmt: Action frame arrived
249 * @len: Action frame length
250 */
251void fst_rx_action(struct fst_iface *iface, const struct ieee80211_mgmt *mgmt,
252		   size_t len);
253
254/**
255 * fst_notify_peer_connected - FST STA connect handler
256 * @iface: FST interface object
257 * @addr: Address of the connected STA
258 */
259void fst_notify_peer_connected(struct fst_iface *iface, const u8 *addr);
260
261/**
262 * fst_notify_peer_disconnected - FST STA disconnect handler
263 * @iface: FST interface object
264 * @addr: Address of the disconnected STA
265 */
266void fst_notify_peer_disconnected(struct fst_iface *iface, const u8 *addr);
267
268/* FST module auxiliary routines */
269
270/**
271 * fst_are_ifaces_aggregated - Determines whether 2 interfaces belong to the
272 *                             same FST group
273 * @iface1: 1st FST interface object
274 * @iface1: 2nd FST interface object
275 *
276 * Returns: %true if the interfaces belong to the same FST group,
277 *          %false otherwise
278 */
279bool fst_are_ifaces_aggregated(struct fst_iface *iface1,
280			       struct fst_iface *iface2);
281
282/**
283 * fst_update_mac_addr - Notify FST about MAC address change
284 * @iface: FST interface object
285 * @addr: New MAC address
286 */
287void fst_update_mac_addr(struct fst_iface *iface, const u8 *addr);
288
289#else /* CONFIG_FST */
290
291static inline int fst_global_init(void)
292{
293	return 0;
294}
295
296static inline int fst_global_start(void)
297{
298	return 0;
299}
300
301static inline void fst_global_stop(void)
302{
303}
304
305static inline void fst_global_deinit(void)
306{
307}
308
309#endif /* CONFIG_FST */
310
311#endif /* FST_H */
312