contrib/wpa/src/fst/fst.h

   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
  39 struct hostapd_hw_modes;
  40 struct ieee80211_mgmt;
  41 struct fst_iface;
  42 struct fst_group;
  43 struct fst_session;
  44 struct fst_get_peer_ctx;
  45 struct fst_ctrl_handle;
  46
  47 struct 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                                      Boolean 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                                     Boolean 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  */
 143 int 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  */
 150 void fst_global_deinit(void);
 151
 152 /**
 153  * struct fst_ctrl - Notification interface for FST module
 154  */
 155 struct 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
 212 struct fst_ctrl_handle * fst_global_add_ctrl(const struct fst_ctrl *ctrl);
 213 void fst_global_del_ctrl(struct fst_ctrl_handle *h);
 214
 215 /**
 216  * NOTE: These values have to be read from configuration file
 217  */
 218 struct 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  */
 233 struct 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  */
 242 void 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  */
 251 void 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  */
 259 void 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  */
 266 void 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  */
 279 Boolean fst_are_ifaces_aggregated(struct fst_iface *iface1,
 280                                   struct fst_iface *iface2);
 281
 282 #else /* CONFIG_FST */
 283
 284 static inline int fst_global_init(void)
 285 {
 286         return 0;
 287 }
 288
 289 static inline int fst_global_start(void)
 290 {
 291         return 0;
 292 }
 293
 294 static inline void fst_global_stop(void)
 295 {
 296 }
 297
 298 static inline void fst_global_deinit(void)
 299 {
 300 }
 301
 302 #endif /* CONFIG_FST */
 303
 304 #endif /* FST_H */