DataPath Driver (80211.o Kernel Module)
The Devicescape DataPath driver is the software that controls the radio hardware on the target device on which the runtime system is deployed. The DataPath driver provides a well-defined interface between the higher-level access point or wireless client functions and the low-level radio drivers.
The DataPath driver is implemented as the kernel module, 80211.o.
Design Overview
This section describes the interface between the DataPath driver and the low-level radio driver package.
To obtain the correct definitions, you must include the ieee80211.h header file in your code.
|
Notes
|
Only ieee80211_tx_status_irqsafe() and ieee80211_rx_irqsave() can be called in hardware interrupt context.The low-level driver must not call any of the DataPath driver interface functions in the context of a hardware interrupt. If there is a need for such call, the low-level driver should first ACK the interrupt and perform the DataPath driver call after this from a scheduled task (for example, in the context of a software interrupt).
The format used when passing frames between the low-level radio drivers and the DataPath driver is the same as used in the wireless media, that is, buffers start with an IEEE 802.11header and include the same octets that are sent over air.
Hardware that uses IEEE 802.3 headers and performs 802.3 to 802.11 conversion in firmware is currently unsupported in the DataPath driver.
Receive frame formats that are not the same as the real frame sent on the wireless media (for example, due to padding) are currently unsupported in the DataPath driver.
|
Data Structures
Transmit Control Fields
The transmit control struct ieee80211_tx_control data structure is passed to low-level driver with each transmitted frame. The low-level driver is responsible for configuring the hardware to use these values to the extent that they are supported by the hardware.
Transmit Status
The transmit status struct ieee80211_tx_status must be provided by the low-level driver to the DataPath driver for each transmitted frame.
Receive Status
The low-level driver must fill in the receive status struct ieee80211_rx_status data structure and pass this information to the DataPath driver with each received frame.
Configuration Block
The struct ieee80211_hw configuration block is used by the low-level driver to tell the DataPath driver about supported hardware features and to pass function pointers for its callback functions.
Some WLAN chipsets generate Beacons in the hardware/firmware. Others rely on host generated beacons. The host_gen_beacon option is used to configure the DataPath driver to generate beacons. The low-level driver can call ieee80211_beacon_gen() to fetch next beacon frame.
Some devices handle decryption internally and do not indicate whether the frame was encrypted (unencrypted frames will be dropped by the hardware, unless specifically allowed through).
Some WLAN chipsets buffer broadcast/multicast frames for power saving stations in the hardware or firmware. Others rely on the host system for such buffering. The host_broadcast_ps_buffering option is used to configure the DataPath driver to buffer broadcast/multicast frames when there are power saving stations so that low-level driver can fetch them with ieee80211_get_buffered_bc().
Handlers
Transmit (tx)
The DataPath driver calls the tx handler for each transmitted frame. skb contains the buffer starting from the 802.11 header. The low-level driver should transmit the frame based on configuration in the Transmit Control Fields.
int (*tx)(struct net_device *dev, struct sk_buff *skb,
struct ieee80211_tx_control *control);
Hardware Reset (reset)
The DataPath driver calls the reset handler to perform a hardware reset.
int (*reset)(struct net_device *dev);
Enable (open)
The DataPath driver calls the open handler when any network device attached to the hardware is set to UP status for the first time. This can be used to enable interrupts and Beacon generation.
int (*open)(struct net_device *dev);
Disable (stop)
The DataPath driver calls the stop handler when any network device attached to the hardware is set to DOWN status for the first time. This can be used to disable interrupts and Beacon generation.
int (*stop)(struct net_device *dev);
Change the Hardware Configuration (config)
The DataPath driver calls the config handler to change the hardware configuration, for example, channel changes.
int (*config)(struct net_device *dev, struct ieee80211_conf *conf);
Set the Traffic Information Map (set_tim)
If the hardware/firmware takes care of Beacon generation, the DataPath driver calls the set_tim handler to tell the low-level driver to set (or clear) the TIM bit for the given Association ID (AID).
If the host system is used to generate Beacons, this handler is not used. The low-level driver should set it to NULL.
int (*set_tim)(struct net_device *dev, int aid, int set);
Set Encryption Keys (set_key)
The DataPath driver calls the set_key handler to set encryption keys. For the default keys, addr is set to ff:ff:ff:ff:ff:ff. It is set to the station hardware address for individual keys. aid of the station is given to help the low-level driver select which hardware key index to use for this key. The Transmit Control Fields contains the hardware key index selected by the low-level driver.
int (*set_key)(struct net_device *dev, set_key_cmd cmd, u8 *addr,
struct ieee80211_key *key, int aid);
Set Transmit Key Index for WEP/TKIP (set_key_idx)
The DataPath driver calls the set_key_idx handler to set the transmit key index for default/broadcast keys. This is needed in cases where the WLAN card is doing full WEP/TKIP encapsulation (wep_include_iv is not set). In other cases, this function pointer can be set to NULL since the DataPath driver takes care of selecting the key index for each transmitted frame.
int (*set_key_idx)(struct net_device *dev, int idx);
Enable/Disable IEEE 8021x (set_ieee8021x)
The DataPath calls the set_ieee8021x handler to enable/disable IEEE 802.1X. This item requests the WLAN card to pass unencrypted EAPOL-Key frames even when encryption is configured. If the WLAN card does not require such a configuration, this function pointer can be set to NULL.
int (*set_ieee8021x)(struct net_device *dev, int use_ieee8021x);
Set Port Authorization State (set_port_auth)
If the WLAN hardware or low-level driver implements Physical Address Extension (PAE), the set_port_auth function can be used to set port authorization state (IEEE 802.1X PAE) to be authorized (authorized=1) or unauthorized (authorized=0). The DataPath Driver will filter frames based on authorization state anyway, so this function pointer can be set to NULL if the low-level driver does not require event notification about port state changes.
int (*set_port_auth)(struct net_device *dev, u8 *addr, int authorized);
Request Passive Scanning (passive_scan)
The DataPath driver calls the passive_scan handler to request the hardware to do a passive scan on a new channel. The hardware is expect to leave the current channel, including transmitting any CTS packets, etc.
int (*passive_scan)(struct net_device *dev, int state,
struct ieee80211_scan_conf *conf);
Return Low-level Statistics (get_stats)
The DataPath driver calls the get_stats handler to request low-level statistics from the device:
int (*get_stats)(struct net_device *dev,
struct ieee80211_low_level_stats *stats);
Enable/Disable Test Modes (test_mode)
The test_mode handler is used to enable/disable test modes (mode = IEEE80211_TEST_)
int (*test_mode)(struct net_device *dev, int mode);
Configure Test Parameters (test_param)
The test_param handler is used to configure test parameters.
int (*test_param)(struct net_device *dev, int param, int value);
Change MAC Address (set_mac_address)
The set_mac_address handler is used to change the MAC address. addr is pointer to struct sockaddr.
int (*set_mac_address)(struct net_device *dev, void *addr);
Set Privacy (set_privacy_invoked)
For devices that generate their own Beacons and probe response or association responses, the set_privacy_invoked handler updates the state of the privacy_invoked . It returns 0 for success or an error number.
int (*set_privacy_invoked)(struct net_device *dev,
int privacy_invoked);
Get Value from Sequence Couter (get_sequence_counter)
For devices that have internal sequence counters, allow the DataPath driver to access the current value of a counter:
int (*get_sequence_counter)(struct net_device *dev,
u8* addr, u8 keyidx, u8 txrx,
u32* iv32, u16* iv16);
Configure RTS Threshold (set_rts_threshold)
The set_rts_threshold handler configures the RTS Threshold (if device needs it).
int (*set_rts_threshold)(struct net_device *dev, u32 value);
Configure Fragmentation Threshold (set_frag_threshold)
set_frag_threshold configures the fragmentation threshold (if device needs it).
int (*set_frag_threshold)(struct net_device *dev, u32 value);
Configure the Retry Limits (set_frag_threshold)
set_retry_limit configures the retry limits (if device needs it).
int (*set_retry_limit)(struct net_device *dev, u32 short_retry,
u32 long_retr);
Request Number of Stations (sta_table_notification)
The sta_table_notification handler gets the number of client Stations (STAs) in the station (STA) table notification. This can be disabled. (NULL = disabled)
void (*sta_table_notification)(struct net_device *dev, int num_sta);
Configure QOS
Configure Queue Parameters (EDCF and Bursting) (conf_tx)
conf_tx configures transmit (TX) queue parameters (EDCF (aifs, cw_min, cw_max), bursting) for a hardware TX queue.
int (*conf_tx)(struct net_device *dev, int queue,
struct ieee80211_tx_queue_params *params);
Get Statistics of Current TX Queue Status (get_tx_stats)
get_tx_stats is used to get number of currently queued packets (queue length), maximum queue size (limit), and total number of packets sent using each transmit (TX) queue (count). This information is used for WMM to find out which TX queues have room for more packets and by hostapd to provide statistics about the current queueing state to external programs.
int (*get_tx_stats)(struct net_device *dev,
struct ieee80211_tx_queue_stats *stats);
Number of Available Hardware Queues (queues)
queues indicates the number of available hardware TX queues for data packets. WMM requires at least four queues.
int queues;
Get TSF Timer Value (get_tsf)
get_tsf gets the current timing synchronization function (TSF) timer value from firmware/hardware. Currently, this is used only for IBSS mode debugging and, as such, is not a required function.
u64 (*get_tsf)(struct net_device *dev);
Reset the TSF Timer (reset_tsf)
reset_tsf resets the TSF timer and allow firmware/hardware to synchronize with other STAs in the IBSS. This is only used in IBSS mode. This function is optional if the firmware/hardware takes full responsibility for TSF synchronization.
void (*reset_tsf)(struct net_device *dev);
Configure Beacon Data for IBSS (beacon_update)
beacon_update sets up Beacon data for IBSS Beacons. Unlike the Access Point (Master), IBSS uses a fixed beacon frame which is configured using this function. This handler is required only for IBSS mode.
int (*beacon_update)(struct net_device *dev, struct sk_buff *skb,
struct ieee80211_tx_control *control);
Determine if Last Beacon Sent by this IBSS (tx_last_beacon)
tx_last_beacon determines whether the last IBSS Beacon was sent by us. This is needed only for IBSS mode and the result of this function is used to determine whether to reply to Probe Requests.
int (*tx_last_beacon)(struct net_device *dev);
DataPath Driver Function Calls
Register Hardware Device
The ieee80211_register_hw function registers a hardware device to the DataPath driver and kernel. The low-level driver must call this function before using any other DataPath driver function. It is called once for each hardware device. The returned pointer must be used to refer to the device when calling other functions. The DataPath driver allocates a private data area for the low-level driver. The size of this area is given as priv_data_len. The ieee80211_dev_hw_data function is used to get a pointer to the private data area.
struct net_device *ieee80211_register_hw(struct ieee80211_hw *hw, size_t
priv_data_len);
|
Note
|
In this version of the interface, the returned pointer is struct net_device *. This may change in the future. The low-level driver must not refer to the device data directly to remain compatible with the future versions.
|
Initialization Completed
The low-level driver should call the ieee80211_hw_initialized function to inform the DataPath driver that it has completed hardware initialization. This function is allowed to update the hardware configuration (for example, the list of supported operation modes and rates).
void ieee80211_hw_initialized(struct net_device *dev, struct ieee80211_hw
*hw);
Remove Hardware Device
The ieee80211_unregister_hw function instructs the DataPath driver to free the allocated resources and remove the net_device from the kernel. A non-zero return value indicates that removing the net_device was not allowed, and the low-level driver must continue to accept calls to its registered handler functions.
int ieee80211_unregister_hw(struct net_device *dev);
Receive Frame Callback
The low-level driver uses the ieee80211_rx function to send the frames it has received to the DataPath driver. The receive buffer (skb) must start with an 802.11 header.
void ieee80211_rx(struct net_device *dev, struct sk_buff *skb, struct
ieee80211_rx_status *status);
Transmit Status Callback
The low-level driver should call the ieee80211_tx_status function to report the status for any transmitted frames that had req_tx_status set in their Transmit Control Fields.
void ieee80211_tx_status(struct net_device *dev, struct sk_buff *skb,
struct ieee80211_tx_status *status);
Beacon Generation
If beacon frames are generated by the host system rather than in hardware/firmware, the low-level driver uses the ieee80211_beacon_gen function to receive the next beacon frame from the DataPath driver. The low-level driver is responsible for calling this function before beacon data is needed (for example, based on a hardware interrupt).
struct sk_buff *ieee80211_beacon_gen(struct net_device *dev, struct
ieee80211_tx_control *control);
Accessing Buffered Broadcast and Multicast Frames
If the hardware/firmware does not implement buffering of broadcast/multicast frames when power saving is used, the DataPath driver buffers them in host memory. The low-level driver uses this function to fetch next buffered frame. In most cases, this is used when generating a beacon frame. The function returns a pointer to the next buffered skb or NULL if no more buffered frames are available.
struct sk_buff *ieee80211_get_buffered_bc(struct net_device *dev, struct
ieee80211_tx_control *control);
|
Note
|
Buffered frames are returned only after a DTIM beacon frame was generated with ieee80211_beacon_gen(). Thus, the low-level driver must call ieee80211_beacon_gen() first. If the previous generated beacon was not DTIM, ieee80211_get_buffered_bc() returns NULL. Therefore, the low-level driver does not need to check for DTIM beacons separately and should be able to use common code for all beacons.
|
Net Interface Operation
802.11 may use more than one kernel net_device for each hardware device. The low-level driver does not "see" these interfaces, so it should use the ieee80211_netif_oper function to perform netif operations on all interfaces.
typedef enum {
NETIF_ATTACH, NETIF_DETACH, NETIF_START, NETIF_STOP, NETIF_WAKE,
NETIF_IS_STOPPED, NETIF_UPDATE_TX_START
} Netif_Oper;
int ieee80211_netif_oper(struct net_device *dev, Netif_Oper op);
Accessing Private Data
Return a pointer to the low-level driver's private data area for a given device.
void *ieee80211_dev_hw_data(struct net_device *dev);
Network Statistics Data
Return a pointer to the network statistics data area for a given device.
void *ieee80211_dev_stats(struct net_device *dev);
