1# net80211 Datapath - Receive 2 3## Overview 4 5This document provides an overview for receive data paths in 6net80211, between the interface to the operating system, through net80211 and 7into the driver. 8 9The details about underlying implementations (eg how A-MPDU RX aggregation 10is handled) will be covered in dedicated documents. 11 12## Concurrency Notes 13 14The transmit path(s), receive path and control / ioctl paths all run 15in parallel and can be scheduled on multiple concurrently running 16kernel threads. It's important to keep this in mind. 17 18## Receive Path 19 20### Concurrency 21 22There must only be one packet receive path into net80211. The net80211 stack 23has not yet been fully validated to ensure that state changes all occur under 24sufficient locking. 25 26### Data Path 27 28The receive path is split into three broad categories: 29 30 * The normal 802.11/802.3 packet receive path from drivers; 31 * The input path for reinjected frames (eg WDS, 802.11s, BPF); 32 * Various side channels for offloaded non-data path (eg explicitly 33 scan results, management frames, etc.) 34 35#### Data Path - Initial Input 36 37The driver receive path begins in ieee80211_input.c . The four 38entry points are: 39 40 * ieee80211_input() / ieee80211_input_mimo() and 41 * ieee80211_input_all() / ieee80211_input_mimo_all(). 42 43The first two are called when the destination MAC address is a known 44(struct ieee80211_node) node. These are passed up to the 45VAP via a call to ni->ni_vap->iv_input(). 46 47The second two are called when the destination MAC address is NOT 48a known node. In this instance, the frames are treated as broadcast 49and routed to each VAP BSS node via a call to ieee80211_input_mimo(). 50 51Each VAP vap->iv_input() method handles the behavioural specific 52needs of the interface. 53 54#### Data Path - VAP type / behaviour 55 56Each VAP type will do roughly the same thing - for example see 57sta_input() in ieee80211_sta.c . 58 59 * Check the frame size and protocol ID; 60 * Check if the frame has been decrypted in hardware; 61 * Grab A-MPDU session frames and put them in the reorder queue; 62 * Handle control frames sent to the node, or general scan frames; 63 * Get the frame QoS information / TID information if present; 64 * If appropriate, check the 802.11 receive sequence number; 65 * Break the handling up into data, management and control; 66 * Reinject into a radiotap/BPF session via a call to 67 ieee80211_radiotap_rx(). 68 69The data paths will typically do the following: 70 71 * Do decryption if needed; 72 * Do 802.11 decap if needed; 73 * Enforce security requirements if needed; 74 * Eventually deliver the frame up to the higher level network 75 stack via a call to ieee80211_deliver_data() which will 76 strip away any last bits of 802.11 / net80211, 77 call ieee80211_vap_deliver_data(), which will call the 78 network stack input interface. 79 80The control and management paths will call vap->iv_recv_mgmt() 81and vap->iv_recv_ctl() which implement the per VAP type behaviours. 82These will include participating in driving the scan engine, 83the per-node state machines and the VAP state machine. 84 85#### Reinjected Path 86 87#### Side Channels 88 89Drivers may need a specific side channel for management/control 90frames, MAC layer events (eg A-MPDU aggregation session state); 91some power state communication, scan information and other 92things that would normally show up as 802.11 frames. 93 94These will be covered in more detail in other documents. 95 96### Receive Status and Parameters 97 98Received 802.11 / 802.3 frames can come with a variety of information 99that isn't strictly the data payload. These include receive timestamps 100(at beginning or end of frame), receive noise floor / signal strength, 101channel / frequency, channel width, received rate, aggregation frame 102boundaries, decryption state, etc. 103 104The original paths - ieee80211_input() and ieee80211_input_all() - 105took a noise floor and rssi parameter. Later drivers provide 106information about all of the above by attaching a (struct ieee80211_rx_stats) 107to the receive mbuf via a call to ieee80211_add_rx_params() bafore 108calling ieee80211_input_mimo() and ieee80211_input_mimo_all() . 109 110Existing drivers should be migrated to the mimo versions of these 111APIs and the existing API should eventually be deprecated and 112replace the mimo versions. 113 114All new drivers must use the ieee80211_input_mimo() and 115ieee80211_input_mimo_all() API calls. 116 117### Driver Receive Path Requirements 118 119The driver receive path has a few top level requirements: 120 121 * Driver / stack locks must not be held during receive. This means that 122 drivers should dequeue their frames first into a local list, release 123 whatever locks are needed and then pass the frames up to net80211. 124 125 * Drivers are responsible for doing the node lookup before 126 calling ieee80211_input() / ieee80211_input_mimo() or 127 calling ieee80211_input_all() / ieee80211_input_mimo_all(). 128 129 * Drivers are also responsible for creating and attaching the 130 ieee80211_rx_stats information via a call to ieee80211_add_rx_params(). 131 132 * Drivers are responsible for tagging a frame as a potential 133 A_MPDU by tagging the received mbuf with the M_AMPDU flag. 134 They should do this by just tagging all mbufs to a node 135 with ni->ni_flags & IEEE80211_NODE_HT set w/ the M_AMPDU flag. 136 This is a holdover from the 802.11n code which enforces that 137 only potential AMPDU frames can be added to an A-MPDU receive 138 aggregation session and may be relaxed / removed in the future. 139 140### Driver Receive Path Methods 141 142Drivers can hook into the receive path processing in a variety of ways. 143There are a number of vap methods that a driver can hook into 144processing. The details will be covered in the driver document. 145 146These include: 147 148 * vap->iv_input - the driver can replace the iv_input method 149 with its own method to first handle frames before they are passed 150 to the VAP type receive path. 151 * vap->iv_recv_mgmt - the driver can hook here to handle 152 management frames before the VAP type management receive path. 153 * vap->iv_recv_ctl - the driver can hook here to handle 154 control frames before the VAP type control receive path. 155 * vap->iv_bmiss - the driver can hook here to be informed of 156 beacon miss frames. 157 158These may be called at any time and overlapping with others (eg 159the beacon miss event - which may be triggered by a timer - 160can be called in parallel with the various receive path methods.) 161