1# SPDX-License-Identifier: BSD-2-Clause 2# 3# Copyright (c) 2023 The FreeBSD Foundation 4# 5# This documentation was written by Björn Zeeb under sponsorship from 6# the FreeBSD Foundation. 7# 8# Redistribution and use in source and binary forms, with or without 9# modification, are permitted provided that the following conditions 10# are met: 11# 1. Redistributions of source code must retain the above copyright 12# notice, this list of conditions and the following disclaimer. 13# 2. Redistributions in binary form must reproduce the above copyright 14# notice, this list of conditions and the following disclaimer in the 15# documentation and/or other materials provided with the distribution. 16# 17# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27# SUCH DAMAGE. 28# 29 30This is a simple program to drive net80211::ieee80211_sta_join1() calls from 31user space. 32 33The program optionally accepts an interface name (e.g., wlan42), or an 34interface name, an SSID and a BSSID. 35 36In the former case of no SSID/BSSID passed it will query the scan results and 37then try to join each entry from the scan with a short delay. 38 39In the lastter case giving the SSID/BSSID one can trigger the "canreassoc" case 40in ieee80211_sta_join1() or not depending on whether one passes the currently 41associated SSID/BSSID or not. 42 43The tool is useful to trigger net80211::newstate() changes while other 44newstate() changes are pending or being executed. 45 46I was specifically developed to show a problem with the LinuxKPI 802.11 compat 47code. The reason is that ieee80211_sta_join1() also calls in (*iv_update_bss)() 48swapping nodes before initiating the state changes and in LinuxKPI state is on 49the sta and not the vif causing all kinds of troubles, especially if we lose 50a state transition before the taskq is run or if the iv_bss node gets swapped 51before a task is executed. 52