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
In March 2020 Phoronix reported that the FreeBSD Foundation would sponsor 802.11ac work (I think based on a Tweet). I started working 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.
What is there now, you wonder?
The iwlwifi driver based on the iwlwifi-next repository along with the latest public firmware (both from early June). This driver was already updated multiple times during the last year of development pulling in support for newer chipsets, bugfixes, and enhancements. Updates were in the order of 20-90 minutes. There will be another update coming in a few days.
- Basic packet passing (ping6 worked for 23 hours), TCP/IPv4 still has hiccups but worked to download release images or surfing web pages.
An enhanced LinuxKPI framework sharing code with drm-kmod and other drivers in base.
- Minor enhancements to net80211.
- About 70 MFCs to stable/13 were done (and while main gets the latest changes stable/13 will get MFCs timely now so people can also test on stable/13, not 13.0-RELEASE)
- Fixes for bhyve so that iwlwifi works in passthru mode (also great for testing).
What is outstanding?
- Some ongoing reviews.
A lot of MFCs to stable/13.
What is not there yet?
- unified mbuf-skbuf
- 802.11n (currently disabled)
- no man pages
What will be added next?
- Full state machine.
- Check what is going on with TCP/UDP/IPv4 again.
- Fixes and enhancements for chipsets as needed.
- Reload support.
- Defered NAPI processing (this seems to bring some timing issues in and is a lot harder to debug just now).
Manual page. -- at this point I would consider iwlwifi a usable replacement for iwm(4) as well.
- Then we'll work on getting 802.11n support over the finish line in net80211 and LinuxKPI and re-enable it in the driver.
- Rinse and repeat for 802.11ac...
- What comes next comes next.
- Q: How can I help?
- A: Patience. We all wanted lots of things for years. They just do not happen over night.
- Q: How can I help?
A: See Testing section below.
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 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 priortize "what's needed next".
- Q: 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: 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: 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.
- Q: Do you have a list of all chipsets working?
- A: Not yet. We'll add to the table below as soon as feedback comes in.
- Q: Which is the best supported chipset?
- A: Not sure there is an answer. Based on demand I am curently mostly testing on AX200.
- 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.
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: What architectures is iwlwifi available for?
- A: The driver is currently build for all architectures which build iwm(4). The other constraint is the architectures LinuxKPI supports. For the moment the only tested architecture is x86_64 (amd64).
- 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 that code will be added.
- Q: What should I do if things don't work?
A: See Testing section below.
- Q: Will you support FreeBSD 13 or 12?
- A: FreeBSD 12 will most likely not be supported any time soon. stable/13 should be in a few weeks once most of the LinuxKPI changes are merged.
- Q: Will you support other drivers but iwlwifi?
- A: Eventually. The main focus currently is on Intel for this project. I am having a look at other permissively licensed drivers in my free time using the same comapt framework.
- Q: Will you accept patches?
- A: Yes, BUT not if they are obviously taken from Linux. 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).
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: I see kldxref errors for ucode (firmware) files.
- A: You can ignore those.
- Q: Can I run FreeBSD inside bhyve with PCI pass-through to test this?
A: 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).
Please fetch the latest "apply-iwlwifi" script from https://people.freebsd.org/~bz/wireless/. The script will then download a number of patches and tarballs and apply them to a local tree. You are expected to run the script from the top of the src/ tree. If you are having other changes in that tree please make sure to have a backup. The tarballs may overwrite files (LinuxKPI netdevice.h being one).
Please add the following lines to /boot/loader.conf or /boot/loader.conf.local.
This will help any possible debugging which needs to be done by making the kernel and drivers more verbose and massively increasing the kernel message buffer.
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. This will also enable 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.
wlans_iwlwifi0="wlan99" create_args_wlan99="wlanmode sta regdomain XXXX country XX" wlandebug_wlan99="+state +crypto +node +auth +assoc +dot1xsm +wpa" ifconfig_wlan99="WPA SYNCDHCP" ifconfig_wlan99_ipv6="inet6 accept_rtadv"
At this point it is only neccessary to rebuild the kernel but no userland. If in doubt please check the FreeBSD Handbook for more information on how to do that. 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.
Loading the driver
(Optional) Before loading the driver clear the kernel message buffer in order to minimize logs running sysctl kern.msgbuf_clear=1.
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. 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 at the bottom of this page)
I have an iwm(4) supported device
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.
What if things go wrong
I am sorry.
- If you get a panic I am sorry. If you have any chanche please configure crash dump support and email me with the panic and the full message buffer contents.
If the firmware crashes, please save a dmesg -a into a file and email it to me.
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.
- If ... (we will fill this as all the possible problems occur).
(Contact details at the bottom of this page)
Currently known issues
- The state machine synchronisation (net80211 to mac80211) does not yet deal with all cases. Part of this is owned to the fact that I wanted to automate some testing. Fixes for this will come the next days.
- In yet undetermined situations packets are not going through or you will see 1..30 second delays.
Which chipset was tested?
Main development chipset.
quz_hr, Comet Lake PCH CNVi WiFi, works as much as the compat framework works.
Wifi 6E (6Ghz) support, needs more work in compat code, FW assert on scan.
You can reach me at (bz at FreeBSD.ORG) or via the freebsd-wireless mailing list. If possible add "[iwlwifi]" to the subject. If possible add the "date" prefix of the files you downloaded and the hash of your git tree to the email body. Let me kindly ask you to give me some time to reply and help; I am not doing this full-time but I will try to acknowledge your email as soon as I can.
- 2021-06-30 "version 0.90 release", some more packets are passing, still strippped down
- 2021-04-01 (date not a joke) first time WPA+packets passing