sys/netproto/802_11/ieee80211_scan.h

   1 /*-
   2  * Copyright (c) 2005-2009 Sam Leffler, Errno Consulting
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  *
  25  * $FreeBSD$
  26  */
  27 #ifndef _NET80211_IEEE80211_SCAN_H_
  28 #define _NET80211_IEEE80211_SCAN_H_
  29
  30 /*
  31  * 802.11 scanning support.
  32  *
  33  * Scanning is the procedure by which a station locates a bss to join
  34  * (infrastructure/ibss mode), or a channel to use (when operating as
  35  * an ap or ibss master).  Scans are either "active" or "passive".  An
  36  * active scan causes one or more probe request frames to be sent on
  37  * visiting each channel.  A passive request causes each channel in the
  38  * scan set to be visited but no frames to be transmitted; the station
  39  * only listens for traffic.  Note that active scanning may still need
  40  * to listen for traffic before sending probe request frames depending
  41  * on regulatory constraints; the 802.11 layer handles this by generating
  42  * a callback when scanning on a ``passive channel'' when the
  43  * IEEE80211_FEXT_PROBECHAN flag is set.
  44  *
  45  * A scan operation involves constructing a set of channels to inspect
  46  * (the scan set), visiting each channel and collecting information
  47  * (e.g. what bss are present), and then analyzing the results to make
  48  * decisions like which bss to join.  This process needs to be as fast
  49  * as possible so we do things like intelligently construct scan sets
  50  * and dwell on a channel only as long as necessary.  The scan code also
  51  * maintains a cache of recent scan results and uses it to bypass scanning
  52  * whenever possible.  The scan cache is also used to enable roaming
  53  * between access points when operating in infrastructure mode.
  54  *
  55  * Scanning is handled with pluggable modules that implement "policy"
  56  * per-operating mode.  The core scanning support provides an
  57  * instrastructure to support these modules and exports a common api
  58  * to the rest of the 802.11 layer.  Policy modules decide what
  59  * channels to visit, what state to record to make decisions (e.g. ap
  60  * mode scanning for auto channel selection keeps significantly less
  61  * state than sta mode scanning for an ap to associate to), and selects
  62  * the final station/channel to return as the result of a scan.
  63  *
  64  * Scanning is done synchronously when initially bringing a vap to an
  65  * operational state and optionally in the background to maintain the
  66  * scan cache for doing roaming and rogue ap monitoring.  Scanning is
  67  * not tied to the 802.11 state machine that governs vaps though there
  68  * is linkage to the IEEE80211_SCAN state.  Only one vap at a time may
  69  * be scanning; this scheduling policy is handled in ieee80211_new_state
  70  * and is invisible to the scanning code.
  71 */
  72 #define IEEE80211_SCAN_MAX      IEEE80211_CHAN_MAX
  73
  74 struct ieee80211_scanner;                       /* scan policy state */
  75
  76 struct ieee80211_scan_ssid {
  77         int      len;                           /* length in bytes */
  78         uint8_t ssid[IEEE80211_NWID_LEN];       /* ssid contents */
  79 };
  80 #define IEEE80211_SCAN_MAX_SSID 1               /* max # ssid's to probe */
  81
  82 /*
  83  * High-level implementation visible to ieee80211_scan.[ch].
  84  *
  85  * The default scanner (ieee80211_scan_sw.[ch]) implements a software
  86  * driven scanner.  Firmware driven scanning needs a different set of
  87  * behaviours.
  88  */
  89 struct ieee80211_scan_methods {
  90         void (*sc_attach)(struct ieee80211com *);
  91         void (*sc_detach)(struct ieee80211com *);
  92         void (*sc_vattach)(struct ieee80211vap *);
  93         void (*sc_vdetach)(struct ieee80211vap *);
  94         void (*sc_set_scan_duration)(struct ieee80211vap *, u_int);
  95         int (*sc_start_scan)(const struct ieee80211_scanner *,
  96             struct ieee80211vap *, int, u_int, u_int, u_int, u_int,
  97             const struct ieee80211_scan_ssid ssids[]);
  98         int (*sc_check_scan)(const struct ieee80211_scanner *,
  99             struct ieee80211vap *, int, u_int, u_int, u_int, u_int,
 100             const struct ieee80211_scan_ssid ssids[]);
 101         int (*sc_bg_scan)(const struct ieee80211_scanner *,
 102             struct ieee80211vap *, int);
 103         void (*sc_cancel_scan)(struct ieee80211vap *);
 104         void (*sc_cancel_anyscan)(struct ieee80211vap *);
 105         void (*sc_scan_next)(struct ieee80211vap *);
 106         void (*sc_scan_done)(struct ieee80211vap *);
 107         void (*sc_scan_probe_curchan)(struct ieee80211vap *, int);
 108         void (*sc_add_scan)(struct ieee80211vap *,
 109             struct ieee80211_channel *,
 110             const struct ieee80211_scanparams *,
 111             const struct ieee80211_frame *,
 112             int, int, int);
 113 };
 114
 115 /*
 116  * Scan state visible to the 802.11 layer.  Scan parameters and
 117  * results are stored in this data structure.  The ieee80211_scan_state
 118  * structure is extended with space that is maintained private to
 119  * the core scanning support.  We allocate one instance and link it
 120  * to the ieee80211com structure; then share it between all associated
 121  * vaps.  We could allocate multiple of these, e.g. to hold multiple
 122  * scan results, but this is sufficient for current needs.
 123  */
 124 struct ieee80211_scan_state {
 125         struct ieee80211vap *ss_vap;
 126         struct ieee80211com *ss_ic;
 127         const struct ieee80211_scanner *ss_ops; /* policy hookup, see below */
 128         void            *ss_priv;               /* scanner private state */
 129         uint16_t        ss_flags;
 130 #define IEEE80211_SCAN_NOPICK   0x0001          /* scan only, no selection */
 131 #define IEEE80211_SCAN_ACTIVE   0x0002          /* active scan (probe req) */
 132 #define IEEE80211_SCAN_PICK1ST  0x0004          /* ``hey sailor'' mode */
 133 #define IEEE80211_SCAN_BGSCAN   0x0008          /* bg scan, exit ps at end */
 134 #define IEEE80211_SCAN_ONCE     0x0010          /* do one complete pass */
 135 #define IEEE80211_SCAN_NOBCAST  0x0020          /* no broadcast probe req */
 136 #define IEEE80211_SCAN_NOJOIN   0x0040          /* no auto-sequencing */
 137 #define IEEE80211_SCAN_GOTPICK  0x1000          /* got candidate, can stop */
 138         uint8_t         ss_nssid;               /* # ssid's to probe/match */
 139         struct ieee80211_scan_ssid ss_ssid[IEEE80211_SCAN_MAX_SSID];
 140                                                 /* ssid's to probe/match */
 141                                                 /* ordered channel set */
 142         struct ieee80211_channel *ss_chans[IEEE80211_SCAN_MAX];
 143         uint16_t        ss_next;                /* ix of next chan to scan */
 144         uint16_t        ss_last;                /* ix+1 of last chan to scan */
 145         unsigned long   ss_mindwell;            /* min dwell on channel */
 146         unsigned long   ss_maxdwell;            /* max dwell on channel */
 147 };
 148
 149 /*
 150  * The upper 16 bits of the flags word is used to communicate
 151  * information to the scanning code that is NOT recorded in
 152  * ss_flags.  It might be better to split this stuff out into
 153  * a separate variable to avoid confusion.
 154  */
 155 #define IEEE80211_SCAN_FLUSH    0x00010000      /* flush candidate table */
 156 #define IEEE80211_SCAN_NOSSID   0x80000000      /* don't update ssid list */
 157
 158 struct ieee80211com;
 159 void    ieee80211_scan_attach(struct ieee80211com *);
 160 void    ieee80211_scan_detach(struct ieee80211com *);
 161 void    ieee80211_scan_vattach(struct ieee80211vap *);
 162 void    ieee80211_scan_vdetach(struct ieee80211vap *);
 163
 164 void    ieee80211_scan_dump_channels(const struct ieee80211_scan_state *);
 165
 166 #define IEEE80211_SCAN_FOREVER  0x7fffffff
 167 int     ieee80211_start_scan(struct ieee80211vap *, int flags,
 168                 u_int duration, u_int mindwell, u_int maxdwell,
 169                 u_int nssid, const struct ieee80211_scan_ssid ssids[]);
 170 int     ieee80211_check_scan(struct ieee80211vap *, int flags,
 171                 u_int duration, u_int mindwell, u_int maxdwell,
 172                 u_int nssid, const struct ieee80211_scan_ssid ssids[]);
 173 int     ieee80211_check_scan_current(struct ieee80211vap *);
 174 int     ieee80211_bg_scan(struct ieee80211vap *, int);
 175 void    ieee80211_cancel_scan(struct ieee80211vap *);
 176 void    ieee80211_cancel_anyscan(struct ieee80211vap *);
 177 void    ieee80211_scan_next(struct ieee80211vap *);
 178 void    ieee80211_scan_done(struct ieee80211vap *);
 179 void    ieee80211_probe_curchan(struct ieee80211vap *, int);
 180 struct ieee80211_channel *ieee80211_scan_pickchannel(struct ieee80211com *, int);
 181
 182 struct ieee80211_scanparams;
 183 void    ieee80211_add_scan(struct ieee80211vap *,
 184                 struct ieee80211_channel *,
 185                 const struct ieee80211_scanparams *,
 186                 const struct ieee80211_frame *,
 187                 int subtype, int rssi, int noise);
 188 void    ieee80211_scan_timeout(struct ieee80211com *);
 189
 190 void    ieee80211_scan_assoc_success(struct ieee80211vap *,
 191                 const uint8_t mac[IEEE80211_ADDR_LEN]);
 192 enum {
 193         IEEE80211_SCAN_FAIL_TIMEOUT     = 1,    /* no response to mgmt frame */
 194         IEEE80211_SCAN_FAIL_STATUS      = 2     /* negative response to " " */
 195 };
 196 void    ieee80211_scan_assoc_fail(struct ieee80211vap *,
 197                 const uint8_t mac[IEEE80211_ADDR_LEN], int reason);
 198 void    ieee80211_scan_flush(struct ieee80211vap *);
 199
 200 struct ieee80211_scan_entry;
 201 typedef void ieee80211_scan_iter_func(void *,
 202                 const struct ieee80211_scan_entry *);
 203 void    ieee80211_scan_iterate(struct ieee80211vap *,
 204                 ieee80211_scan_iter_func, void *);
 205 enum {
 206         IEEE80211_BPARSE_BADIELEN       = 0x01, /* ie len past end of frame */
 207         IEEE80211_BPARSE_RATES_INVALID  = 0x02, /* invalid RATES ie */
 208         IEEE80211_BPARSE_XRATES_INVALID = 0x04, /* invalid XRATES ie */
 209         IEEE80211_BPARSE_SSID_INVALID   = 0x08, /* invalid SSID ie */
 210         IEEE80211_BPARSE_CHAN_INVALID   = 0x10, /* invalid FH/DSPARMS chan */
 211         IEEE80211_BPARSE_OFFCHAN        = 0x20, /* DSPARMS chan != curchan */
 212         IEEE80211_BPARSE_BINTVAL_INVALID= 0x40, /* invalid beacon interval */
 213         IEEE80211_BPARSE_CSA_INVALID    = 0x80, /* invalid CSA ie */
 214 };
 215
 216 /*
 217  * Parameters supplied when adding/updating an entry in a
 218  * scan cache.  Pointer variables should be set to NULL
 219  * if no data is available.  Pointer references can be to
 220  * local data; any information that is saved will be copied.
 221  * All multi-byte values must be in host byte order.
 222  */
 223 struct ieee80211_scanparams {
 224         uint8_t         status;         /* bitmask of IEEE80211_BPARSE_* */
 225         uint8_t         chan;           /* channel # from FH/DSPARMS */
 226         uint8_t         bchan;          /* curchan's channel # */
 227         uint8_t         fhindex;
 228         uint16_t        fhdwell;        /* FHSS dwell interval */
 229         uint16_t        capinfo;        /* 802.11 capabilities */
 230         uint16_t        erp;            /* NB: 0x100 indicates ie present */
 231         uint16_t        bintval;
 232         uint8_t         timoff;
 233         uint8_t         *ies;           /* all captured ies */
 234         size_t          ies_len;        /* length of all captured ies */
 235         uint8_t         *tim;
 236         uint8_t         *tstamp;
 237         uint8_t         *country;
 238         uint8_t         *ssid;
 239         uint8_t         *rates;
 240         uint8_t         *xrates;
 241         uint8_t         *doth;
 242         uint8_t         *wpa;
 243         uint8_t         *rsn;
 244         uint8_t         *wme;
 245         uint8_t         *htcap;
 246         uint8_t         *htinfo;
 247         uint8_t         *ath;
 248         uint8_t         *tdma;
 249         uint8_t         *csa;
 250         uint8_t         *quiet;
 251         uint8_t         *meshid;
 252         uint8_t         *meshconf;
 253         uint8_t         *spare[3];
 254 };
 255
 256 /*
 257  * Scan cache entry format used when exporting data from a policy
 258  * module; this data may be represented some other way internally.
 259  */
 260 struct ieee80211_scan_entry {
 261         uint8_t         se_macaddr[IEEE80211_ADDR_LEN];
 262         uint8_t         se_bssid[IEEE80211_ADDR_LEN];
 263         /* XXX can point inside se_ies */
 264         uint8_t         se_ssid[2+IEEE80211_NWID_LEN];
 265         uint8_t         se_rates[2+IEEE80211_RATE_MAXSIZE];
 266         uint8_t         se_xrates[2+IEEE80211_RATE_MAXSIZE];
 267         union {
 268                 uint8_t         data[8];
 269                 u_int64_t       tsf;
 270         } se_tstamp;                    /* from last rcv'd beacon */
 271         uint16_t        se_intval;      /* beacon interval (host byte order) */
 272         uint16_t        se_capinfo;     /* capabilities (host byte order) */
 273         struct ieee80211_channel *se_chan;/* channel where sta found */
 274         uint16_t        se_timoff;      /* byte offset to TIM ie */
 275         uint16_t        se_fhdwell;     /* FH only (host byte order) */
 276         uint8_t         se_fhindex;     /* FH only */
 277         uint8_t         se_dtimperiod;  /* DTIM period */
 278         uint16_t        se_erp;         /* ERP from beacon/probe resp */
 279         int8_t          se_rssi;        /* avg'd recv ssi */
 280         int8_t          se_noise;       /* noise floor */
 281         uint8_t         se_cc[2];       /* captured country code */
 282         uint8_t         se_meshid[2+IEEE80211_MESHID_LEN];
 283         struct ieee80211_ies se_ies;    /* captured ie's */
 284         u_int           se_age;         /* age of entry (0 on create) */
 285 };
 286 #ifdef MALLOC_DECLARE
 287 MALLOC_DECLARE(M_80211_SCAN);
 288 #endif
 289
 290 /*
 291  * Template for an in-kernel scan policy module.
 292  * Modules register with the scanning code and are
 293  * typically loaded as needed.
 294  */
 295 struct ieee80211_scanner {
 296         const char *scan_name;          /* printable name */
 297         int     (*scan_attach)(struct ieee80211_scan_state *);
 298         int     (*scan_detach)(struct ieee80211_scan_state *);
 299         int     (*scan_start)(struct ieee80211_scan_state *,
 300                         struct ieee80211vap *);
 301         int     (*scan_restart)(struct ieee80211_scan_state *,
 302                         struct ieee80211vap *);
 303         int     (*scan_cancel)(struct ieee80211_scan_state *,
 304                         struct ieee80211vap *);
 305         int     (*scan_end)(struct ieee80211_scan_state *,
 306                         struct ieee80211vap *);
 307         int     (*scan_flush)(struct ieee80211_scan_state *);
 308         struct ieee80211_channel *(*scan_pickchan)(
 309                         struct ieee80211_scan_state *, int);
 310         /* add an entry to the cache */
 311         int     (*scan_add)(struct ieee80211_scan_state *,
 312                         struct ieee80211_channel *,
 313                         const struct ieee80211_scanparams *,
 314                         const struct ieee80211_frame *,
 315                         int subtype, int rssi, int noise);
 316         /* age and/or purge entries in the cache */
 317         void    (*scan_age)(struct ieee80211_scan_state *);
 318         /* note that association failed for an entry */
 319         void    (*scan_assoc_fail)(struct ieee80211_scan_state *,
 320                         const uint8_t macaddr[IEEE80211_ADDR_LEN],
 321                         int reason);
 322         /* note that association succeed for an entry */
 323         void    (*scan_assoc_success)(struct ieee80211_scan_state *,
 324                         const uint8_t macaddr[IEEE80211_ADDR_LEN]);
 325         /* iterate over entries in the scan cache */
 326         void    (*scan_iterate)(struct ieee80211_scan_state *,
 327                         ieee80211_scan_iter_func *, void *);
 328         void    (*scan_spare0)(void);
 329         void    (*scan_spare1)(void);
 330         void    (*scan_spare2)(void);
 331         void    (*scan_spare4)(void);
 332 };
 333 void    ieee80211_scanner_register(enum ieee80211_opmode,
 334                 const struct ieee80211_scanner *);
 335 void    ieee80211_scanner_unregister(enum ieee80211_opmode,
 336                 const struct ieee80211_scanner *);
 337 void    ieee80211_scanner_unregister_all(const struct ieee80211_scanner *);
 338 const struct ieee80211_scanner *ieee80211_scanner_get(enum ieee80211_opmode);
 339 void    ieee80211_scan_update_locked(struct ieee80211vap *vap,
 340                 const struct ieee80211_scanner *scan);
 341 void    ieee80211_scan_copy_ssid(struct ieee80211vap *vap,
 342                 struct ieee80211_scan_state *ss,
 343                 int nssid, const struct ieee80211_scan_ssid ssids[]);
 344 void    ieee80211_scan_dump_probe_beacon(uint8_t subtype, int isnew,
 345                 const uint8_t mac[IEEE80211_ADDR_LEN],
 346                 const struct ieee80211_scanparams *sp, int rssi);
 347 void    ieee80211_scan_dump(struct ieee80211_scan_state *ss);
 348
 349 #endif /* _NET80211_IEEE80211_SCAN_H_ */