mac80211 driver-level interface semantics

One of the huge advantages of mac80211 is that we can improve consistency between drivers. However there is still work needed to define some semantics in order to make all drivers behave similarly.

This document is under development and might not be 100% correct. It is mostly modelled on the current behaviour of the bcm43xx driver.

add_interface vs open

The add_interface ieee80211_op should be used for initializing the device when the user wants to use it. The 2nd parameter (struct ieee80211_if_init_conf *conf) should be used to determine the interface type, and you may need to store conf->if_id for later calls back into mac80211 regarding this interface.

The open ieee80211_op should not be used and may potentially be removed in future. Same goes for stop: use remove_interface.

You need to do reference counting on your interfaces, otherwise you might make mistakes like powering down the radio in remove_interface when there is still another interface active.

add_interface gets called when the user brings the interface up, and remove_interface gets called when the user brings the interface down (FIXME check this)

Monitor interfaces

A hard monitor interface is created when the user changes the mode of the initial interface to monitor and brings it up, e.g.:

<plug in device>
# iwconfig wlan0 mode monitor
# ifconfig wlan0 up

Such an interface should forward all received frames to the stack that have a valid PLCP checksum and a valid FCS (CRC check.) FootNote(In the future, we may devise a way to indicate FCS/PLCP checksum failures to the stack. until then, such frames must never be passed to mac80211)

A soft monitor interface is created when the user creates an additional interface alongside the original one and brings it up, e.g.:

FIXME how does a user do this?

For soft interfaces, you should not attempt to reprogram the hardware to send more frames up than usual. Continue to ignore short frames, frames with bad CRCs, etc. The one exception here is that if you are not doing so already, you should reprogram the hardware to send CTL frames (e.g. ACKs) up to the host, and your driver should then send them up to the stack.

During add_interface, your driver can distinguish between hard and soft as follows:

If there are non-monitor interfaces present, you become a soft monitor interface. (you know this in your driver because you are reference-counting your interfaces)
Otherwise, if there are no non-monitor interfaces present, you become a hard monitor interface.
If there are only hard monitor interfaces present during add_interface for a non-monitor interface, you should demote existing monitors into soft monitor interfaces.

During remove_interface, apply the following logic:

After the interface in question is removed, if there are no non-monitor interfaces remaining, promote all soft monitor interfaces into hard monitor interfaces.

MAC addresses

Typically, drivers read a MAC address from EEPROM and write it into a device register. You should read the EEPROM during initial probe and store it in wiphy->perm_addr, however you should not initially program it into the active device to avoid it acking frames.

When an interface is added, look at conf->mac_addr. Program this into your hardware when appropriate:

For non-monitor interfaces, program it unconditionally
For hard monitor interfaces, program a zero mac address into the hardware so that it does not ACK any frames.

conf->mac_addr will be NULL for monitor interfaces: don't unconditionally dereference it.

Remember to apply remove_interface considerations to MAC address too, e.g. take this scenario:

add_interface called for a managed interface
- mac address programmed into hardware from conf->mac_addr
add_interface called for a monitor interface
- a non-monitor exists, so this is a soft monitor interface: don't mess with the MAC address
remove_interface called for the manged interface
- the soft monitor interface is now promoted to a hardware monitor interface, so you should program a zero MAC address

Firmware

Firmware should not be loaded during the probe operation, it should be deferred until the first time an interface is added. However, your driver should read the device MAC address during probe and store it in wiphy (the mac address should be available before the interface comes up, much of userspace relies on this).

Sidenote: this assumes that you have a mechanism for reading the MAC address before firmware is loaded. This is true for all existing drivers, and will hopefully remain that way for future drivers too.

During add_interface, if firmware is not found, return ENOENT. This will get passed up to userspace which will interpret in terms of "firmware not found".