Phoronix reported (March 2020) that the FreeBSD Foundation would sponsor 802.11ac wireless work (I think based on a Tweet). I started working on the Intel driver and wireless in April 2020 (with some gaps). At that point in time FreeBSD had (and still has) iwn(4) and iwm(4) support for various (older) Intel chipsets. There were various requests on the mailing lists and the bug tracking system for support for newer chipsets. There were also requests for drivers from other vendors. I did not feel that FreeBSD would have the man power at that point to write (or port and keep up-to-date from another BSD) native drivers for all the wireless cards (often exceeding the size of a wired driver by a magnitude in size these days). We also had no-one working on both sides of drivers anymore (having vendor resources or firmware access) and hence are dependent on public information to write drivers. This lead to multiple points:

• the decision made was to write compat code for 802.11 so that the friendly-licensed drivers could just be used mostly as-are and be pulled-in from upstream (hopefully) without too much changes quickly,
• the Intel iwlwifi driver was chosen to be used to develop 802.11ac station support. In addition to user-requests, the Dual-License of the newer driver parts (we can simply take the BSD license code, whereas we cannot take any GPL-only code into the tree anymore), already support for 11ax, the clean code structure, previous examples of ports of older versions of the driver, the ability to distribute firmware, .. all played into the decision,
• the ability to (eventually) feed changes back to the drivers, engaging with vendors, and helping a common goal of having good quality drivers.

Upfront I would love to thank the FreeBSD Foundation for sponsoring most of this project. I would also love to thank everyone who has reviewed changes, did initial testing, helped with drm-kmod, helped in various other ways, answered questions, encouraged, or patiently waited for any results or running code. – BjoernZeeb, 20210619

The iwlwifi driver based on upstream Linux iwlwifi-next repository along with the firmware from linux-firmware.git. This driver was already updated multiple times during the last year of development pulling in support for newer chipsets, bugfixes, and enhancements. Updates were on the order of 20-90 minutes. We will keep updating as iwlwifi moves forward.

• Basic packet passing for surfing web pages.
• An enhanced LinuxKPI framework sharing code with drm-kmod and other drivers in base.
• Rewritten LinuxKPI 802.11 state machine to keep net80211 and mac80211 better in sync.
• Minor enhancements to net80211.
• Constant MFCs to stable/13. While main gets the latest changes, stable/13 gets MFCs currently so people can test on stable/13.
• Fixes for bhyve so wireless works in passthru mode (also great for testing).
• Basic deferred NAPI processing, necessary for other changes. This brings some timing adjustments, making things a bit harder to debug at the moment.
• Initial manual pages.
• Driver auto-loading from devmatch(8). Anything working with iwm(4) will attach to iwm(4) and not iwlwifi(4) by default.

Projects funded by The FreeBSD Foundation:

• WiFi update – Intel drivers and 802.11ac
• Wireless Internship

• Fixes and enhancements for chipsets, LinuxKPI, and net80211 as needed (please test and report issues and successes!) along with their timely merges to stable/13.
• Stability work.

1. Reload support (to deal with firmware crashes).
2. Complete 802.11n support in net80211, LinuxKPI and re-enable it in the driver.
3. suspend/resume support
4. 802.11ac support
5. Unified mbuf-skbuf
6. 802.11ax support, ..

• Q: Which cards are supported? A: Most modern ones including some which do not even ship yet. For a full list see here.
  

• Q: Do you have a list of all chipsets working? A: We collected that information early on but stopped as it was no longer practical to track each user report.
  A: Unless there are issues now, the assumption should be that at least all non-iwm(4) supported chipsets work.
  

• Q: Which is the best supported chipset? A: Not sure there is an answer. Based on demand I am currently mostly testing on AX200 and AX210.
  

• Q: Does this driver support the AX210 from the Framework Laptop? A: Yes it does.
  

• Q: Upon start we associate and immediately drop back and associate again. What is going on there? A: After associating the firmware/driver reports beacon losses or connection loss and subsequently we take the state down to recover. On second attempt we seem to usually succeed.
  A: It is unclear as to where this behavior comes from but similar reports were seen from Linux users in the last two years and speculations are that it could be a firmware issue.
  

• Q: How do I stop devmtach from automatically loading if_iwlwifi? A: Add devmatch_blocklist="if_iwlwifi" to rc.conf.
  A: Similar you can also prevent iwm(4) from being loaded if you want to try iwlwifi(4).
  

• Q: How should I load the driver and the firmware? A: you should not need to anymore; devmatch will automatically do it for you.
  A: If you want to do it manually: kld_list="${kld_list} if_iwlwifi" in rc.conf is the best way currently.
  A: Longer: Historically people compiled the driver into the kernel or loaded the modules from loader. With devmatch(8) this is not neccessary anymore as drivers would auto-load and loading the driver from multi-user is faster anyway than using time in loader.
  A: If you want to load from loader for other reasons see this freebsd-wireless thread and the Chipsets list for which firmware to pick if you do not know.
  

• Q: How can I help? A: Testing and feedback! Given the driver is in FreeBSD git you can just give it a try on main and stable/13.
  A: See also Testing section below.
  

• Q: Why does X not work yet? A: Patience. We all wanted lots of things for years. They just do not happen over night.
  

• Q: I have an iwm(4) wireless card, can I try the new driver but fallback to iwm(4) for daily use for now? A: Yes! See devmatch question above and Testing section below.
  

• Q: I have an iwn(4) wireless card, can I try the new driver? A: No. The dwm support of the iwlwifi driver is GPL-only code and thus not supported.
  

• Q: You list a lot of things still TODO. Is it worth testing? A: Yes! It will always be good to know if your card is detected correctly and works. It will also help to prioritize “what's needed next”. You may even get packets these days.
  A: In addition for newer cards this may be the only option you have.
  

• Q: After boot there is no wlan0 device? A: if_iwlwifi.ko currently is not auto-loading. In case something goes wrong the next boot will not leave you in an endless loop of problems. Auto-loading support is in Phabricator and will be re-added at a later time for all LinuxKPI based drivers.
  A: This should no longer happen if you have configured the wlan in rc.conf. Please double-check your configuration or see if there were any errors in dmesg and report them back.
  

• Q: I see iwl-debug-yoyo.bin: could not load firmware image, error 2. Is that a problem? A: You likely have bootverbose enabled (as I told you). No this is not a problem (and expected). Please ignore. The yoyo is not for everyone to play with
  

• Q: I see warnings about firmware files not being loaded and a number counting down. Help? A: The iwlwifi driver often supports firmware which is newer than what is publicly available and tries to load any supported version from new to old until it finds a firmware. In general this can be ignored.
  

• Q: What architectures is iwlwifi available for? A: The driver is currently build for i386, amd64, and arm64 architectures supporting LinuxKPI. For the moment the main tested architecture is x86_64 (amd64) and I do some testing on Aarch64 (arm64).
  

• Q: When will “feature X” be available? A: The obvious answer is “yesterday” (as we'd all wish), the realistic answer is “when it is done”.
  

• Q: Why is there no “restart” support? Why is there no full state machine? A: During the initial testing having things mostly stop if something goes wrong is very helpful for analysis and automatic restart would mask a lot of problems. Once we are confident that things work to a certain level the restart code will be added.
  A: The full state machine is there these days but there are rough edges on shutdown still as net80211 and mac80211 do not always align that we are trying to smooth out over time.
  

• Q: What should I do if things don't work? A: See Testing section below.
  A: If possible check this wiki, linked PRs, and the freebsd-wireless mailing list archives first. If you cannot find a solution already please report the issue.
  

• Q: Will you support FreeBSD 13 or 12? A: FreeBSD 13 is supported in the stable/13 branch (not 13.0-RELEASE). The first release to contain this driver code is 13.1-RELEASE.
  A: FreeBSD 12 will not be supported.
  

• Q: Will you accept patches? A: Yes, but we can't accept code taken from directly from Linux due to GPL licensing. drm-kmod is stuck outside the tree because of linuxkpi-gplv2 code. History shall not repeat itself. If you have patches please contact me (Contacts at the end of this page) or open a PR or even better a review on Phabricator.
  

• Q: I see (two) lkpi_ic_getradiocaps: Adding chan ... returned error 55 messages. Should I be concerned? A: These are harmless and can be ignored.
  A: This warning was fixed in cee56e77d77909df69624cc707a571647651c853.
  

• Q: Can I run FreeBSD inside bhyve with PCI pass-through to test this? A: Yes you can on recent main and stable/13.
  A: there is a patch for bhyve on HEAD to be tested in https://reviews.freebsd.org/D32359 which allows Intel wireless cards to work as passthru device. Now in main as main commit 7fa2335347362378322a4d27cb40f6e6cd5dd0fb.
  There is a patch for bhyve on HEAD to be tested in https://reviews.freebsd.org/D31241 which allows Intel wireless cards to work as passthru device. The change seems to apply and build on stable/13 as well. The previous PR257273 was closed in favour of this and the old patch 20210709-01-iwlwifi-disable-msix.diff to disable MSI-X is no longer needed (but still available for people who cannot update bhyve yet, e.g. running a release) (you need to set kenv compat.linuxkpi.iwlwifi_disable_msix=1 before loading the driver inside the guest or add the entry to loader.conf: compat.linuxkpi.iwlwifi_disable_msix=1).)–
  A: There were actually more changes to improve pci passthru for iwlwifi
  

• Q: (Obsolete) I see kldxref errors for ucode (firmware) files. A: You can ignore those for now.
  A: There is a problem. For more details see here: D32383
  A: All changes needed are in FreeBSD git branches main and stable/13.
  

• Q: (Obsolete) I tried snapshot one and it worked but snapshot 2 (20210906) does not start and gives a firmware assertion. What can I do? A: Try setting kenv compat.linuxkpi.debug_napi=0x1000 prior to loading the kernel modules or sysctl compat.linuxkpi.debug_napi=0x1000 if the linuxkpi module is already loaded and see if that helps. Please report back!
  A: Please try again based on FreeBSD git branches main and stable/13 and if it still happens and is not covered elsewhere, please report back.
  

• Q: (Obsolete) Your latest snapshot no longer applies. What shall I do? A: We are working on getting all parts into the tree currently. Please be patient for a few more days.)
  A: All changes are in FreeBSD git branches main and stable/13. There are no more snapshots. Please track the appropriate branch.
  

• Q: (Obsolete) Do you have a git tree I can clone? A: No. You may have noticed that the split-up of files is ready for moving into the tree. Were all essential bits in-tree I would have added the driver as a “local module” like drm-kmod is. The other hope is that this can 1:1 be applied to 13 later. If people prefer to clone a full tree I can apply the changes and provide one. Let me know.
  A: Yes. All changes are in FreeBSD git branches main and stable/13. Please track the official FreeBSD git repo.
  

• Q: (Obsolete) Why do I have to patch and re-compile my kernel? A: Because not all changes are externally loadable and not all are reviewed and committed to main. The plan is to get essential changes into the tree as soon as possible so that the rest could be distributed externally for the moment.
  

• Q: (Obsolete) Why do you not just commit the driver to main? A: Some of the files no longer have license text and only SPDX tags. Core is working on a policy change for that. We decided I'll give them time and not shortcut this driver in.
  

• Q: Why did you not port the iwx(4) driver from OpenBSD? A: There were other people looking into this. When I started there was limited support for various chipsets already supported by iwlwifi, the code was highly BSD-ified and mangled so that comparing to the original code was not longer possible in an automated way and it would have helped any other of the goals listed above and it would have added another driver to change and support (in addition to iwm).
  

• Q: Will you support other new drivers but iwlwifi? A: Yes , eventually we do. The main focus is on Intel for this project. I am having a look at other permissively licensed drivers using the same compat framework. Snapshots or links to other wiki pages are normally here.

• If you get a panic I am sorry. Please configure crash dump support and email me with the panic and the full message buffer contents. See testing for some hints.
• If the firmware crashes, please save a dmesg -a into a file and email it to me. Note: the real error usually happens before the firmware traceback. Try to share that too please.
• If the driver does not load (kldload complains) please check dmesg -a | tail -10 for information. You are likely missing symbols, which means your tree is too old or your are running a custom kernel config and the code is missing a dependency. This should not happen if you build a GENERIC in-tree from FreeBSD git.

• State machine synchronization (net80211 to mac80211) does not yet deal with all cases (roaming, stop/start, ..).
• Queue <n> is stuck <x> <y> observed a few times… some extra debug printf for this case
• The “connection loss” / “beacon loss” issue mentioned in the FAQ section. (rarely seen since the fix Jun 26 2022 ed3ef56b29fd194a5ac0b820fd09bf01a4922bb7 ?)
• Invalid TXQ id observed a few times.. some extra debug printf for this case currently assumed fix
• Scanning and association doesn't always work (there were also overlapping wpa_supplicant issues). (Status: OK in next snapshot)
• Panic in ieee80211_radiotap_active_vap().
• LMAC not starting (firmware assertion). (Status: OK in next snapshot, or needs more testing and feedback)
• High fan activity on notebook. (Status: OK in next snapshot)
• Older cards are running into a constant firmware crash during association currently (2022-April-May-???); fixed by ed3ef56b29fd194a5ac0b820fd09bf01a4922bb7 (June 26)

Instead of tracking each bug here, there is a 'meta-bug' in Bugzilla which depends on all iwlwifi PRs. Please check those first before reporting a new PR.

• iwlwifi meta-bug

• Email: bz@FreeBSD.org
• freebsd-wireless mailing list

Please include:

• [iwlwifi] in the Subject
• FreeBSD branch and commit hash of your git src tree which you are running, in the email body

Please allow me some time to reply and help; I am not doing this full-time but I will try to acknowledge email as soon as I can.

• Please checkout either main or stable/13 from FreeBSD git.

• Fetch the latest “apply-wireless” script from https://people.freebsd.org/~bz/wireless/.
• Run the script from the top of the src/ tree.
  • If your src tree has other modifications, take a backup before running it.
• The script will download patches and tarballs and apply them to a local tree. Note: The tarballs may overwrite files (LinuxKPI netdevice.h being one).

In order to help debugging it is advisable to add the following lines to /boot/loader.conf or /boot/loader.conf.local

boot_verbose="YES"
kern.msgbufsize=1146880

This will help making the kernel and drivers more verbose and massively increasing the kernel message buffer to keep more information.

You want to setup wireless configuration in /etc/rc.conf and probably /etc/wpa_supplicant.conf if you have not done so already. There is some information in the FreeBSD Handbook to help you getting started.

Here is a short sample I copied from a test setup. For rc.conf I assume a wlan99 (while most people will likely use wlan0 or wlan1). You will have to replace the XX bits with something suitable to your location. You can also enable some wlan debugging so we can try to see what happened in case something goes wrong. If you have your own configuration already please add the wlandebug line in case you experience problems. Feel free to add/remove flags as you see fit or ask if in doubt. `man wlandebug' has a list of all flags and descriptions for each.

wlans_iwlwifi0="wlan99"
create_args_wlan99="wlanmode sta regdomain XXXX country XX"
#wlandebug_wlan99="+state +node +auth +assoc +dot1xsm +wpa +scan"
ifconfig_wlan99="WPA SYNCDHCP"
ifconfig_wlan99_ipv6="inet6 accept_rtadv"

It is only necessary to rebuild the kernel, not userland at this point.

Check the FreeBSD Handbook:: Kernel Configuration for instructions.

Reboot your system to the newly installed kernel.

You may see a lot more messages on the screen due to “boot_verbose” being on, which you may not be used to.

In a normal setup the driver will be auto-loaded for you nowadays and you do not have to do anything.

Should debugging require manual intervention here are the (old) notes from the early days which can still be useful:

(Optional) Sometimes it makes sense to disable auto-loading of the driver. In that case you may want to clear the kernel message buffer in order to minimize logs running sysctl kern.msgbuf_clear=1.

If not auto-loaded already, kldload /boot/kernel/if_iwlwifi.ko should load the driver and you should see some information scrolling on the console.

(If you are using iwm(4) please see below at this point.)

A sysctl net.wlan.devices should now list iwlwifi0 as a possible wireless device.

If it does and you have not yet automatically gotten a wlan<n> device (see ifconfig -l) you can now run sh /etc/rc.d/netif start wlan99 (or wlan0 or wlan1 depending on your setup). Depending on your configuration WPA and then DCHPv4 may run, IPv6 will autoconfigure and you should see the output from ifocnfig about the wireless device.

You can test and see what is working. At this point please do not expect a fully-functional device giving you 11ac. Should anything go wrong, simply toggling the interface or unloading and reloading the driver will likely not be enough and you will have to reboot.

If you get to this point, please email me a sample of your log and the pciconf -lv lines for the iwlwifi0 entry so we can add the information to the table below. (Contact details can be found on this page)

If you have an iwm(4) supported device, you will need to detach the iwm(4) and attach iwlwifi. Please check pciconf -l for your wireless device and remember (or copy and paste later) the first bit.

% pciconf -l | grep iwm
iwm0@pci0:3:0:0:        class=0x028000 rev=0x78 hdr=0x00 vendor=0x8086 device=0x24fd subvendor=0x8086 subdevice=0x0010

After loading the iwlwifi kernel module run the following commands (replacing the device selector with what you found for your computer):

devctl detach pci0:3:0:0
devctl set driver pci0:3:0:0 iwlwifi

That should do the trick.

For a full list of supported chipsets see here.

Which chipsets have been tested? This list is here from the early days of driver upbringing and testing and is no longer maintained actively. Feel free to add your card with status and a possible reference to a bsd-hardware.info report or a reference of a posting to public wireless list.

To keep track and references to some problems or other significant changes during development / testing:

• iwlwifi: 8260: frequently disconnects since Linux 5.1 "No beacon heard and the time event is over already" - WIFI-25906
• iwlwifi: Make missed beacon timeout configurable – do not think this will help anything as the problem seems in FW
• BUGFIX iwlwifi: mvm: Allow multicast data frames only when authorized
• Bug 203593 - iwlwifi: 9560: Unhandled alg: 0x707 - WIFI-24625 handled locally in FreeBSD, should extract and upstream

• 2022-06-03 Update was merged to stable/13.
• 2022-05-16 Driver and firmware get updated to resemble what will likely ship in Linux 5.18. Changes are now less than 400 lines in shared files.
• 2022-05-16 FreeBSD 13.1-RELEASE ships with a version from beginning of April.
• 2022-02-24 Driver and firmware get updated in main. Massively reduces changes as Intel has taken care of void * arithmetic and const handling.
• 2021-12-30 Driver gets merged to stable/13
• 2021-12-27 Work as-is is all in HEAD and attached to build.
• 2021-11-28 The driver and firmware went into HEAD (detached from build)
• 2021-09-06 “version 0.91 release”, 11a/b/g seem usable
• 2021-06-30 “version 0.90 release”, some more packets are passing, still stripped down
• 2021-04-01 (date not a joke) first time WPA+packets passing