|
wpa_supplicant / hostapd
2.5
|
|
wpa_supplicant / hostapd
2.5
|
Wi-Fi Direct functionality is implemented any many levels in the WLAN stack from low-level driver operations to high-level GUI design. This document covers the parts that can be user by wpa_supplicant. However, it should be noted that alternative designs are also possible, so some of the functionality may reside in other components in the system.
The driver (or WLAN firmware/hardware) is expected to handle low-level operations related to P2P Power Management and channel scheduling. In addition, support for virtual network interface and data frame processing is done inside the driver. Configuration for these low-level operations is defined in the driver interface: src/drivers/driver.h. This defines both the commands and events used to interact with the driver.
P2P module implements higher layer functionality for management P2P groups. It takes care of Device Discovery, Service Discovery, Group Owner Negotiation, P2P Invitation. In addition, it maintains information about neighboring P2P Devices. This module could be used in designs that do not use wpa_supplicant and it could also reside inside the driver/firmware component. P2P module API is defined in src/p2p/p2p.h.
Provisioning step of Group Formation is implemented using WPS (src/wps/wps.h).
wpa_supplicant includes code in interact with both the P2P module (wpa_supplicant/p2p_supplicant.c) and WPS (wpa_supplicant/wps_supplicant.c). The driver operations are passed through these files, i.e., core P2P or WPS code does not interact directly with the driver interface.
P2P functionality affects many areas of the system architecture. This section shows couple of examples on the location of main P2P components. In the diagrams below, green arrows are used to show communication paths from the P2P module to upper layer management functionality and all the way to a GUI that user could use to manage P2P connections. Blue arrows show the path taken for lower layer operations. Glue code is used to bind the P2P module API to the rest of the system to provide access both towards upper and lower layer functionality.
An architecture where the P2P module resides inside the wpa_supplicant process is used with Linux mac80211-based drivers, e.g., ath9k. The following diagram shows the main components related to P2P functionality in such an architecture.
The following diagram shows the main components related to P2P functionality in an architecture where the P2P module resides inside the kernel IEEE 802.11 stack (UMAC in the figure).
P2P module manages discovery and group formation with a single state machine, i.e., only a single operation per device can be in progress at any given time. The following diagram describes the P2P state machine. For clarity, it does not include state transitions on operation timeouts to the IDLE state. The states that are marked with dotted ellipse are listed for clarity to describe the protocol functionality for Device Discovery phase, but are not used in the implementation (the SEARCH state is used to manage the initial Scan and the alternating Listen and Search states within Find).
P2P module API is defined in src/p2p/p2p.h. The API consists of functions for requesting operations and for providing event notifications. Similar set of callback functions are configured with struct p2p_config to provide callback functions that P2P module can use to request operations and to provide event notifications. In addition, there are number of generic helper functions that can be used for P2P related operations.
These are the main functions for an upper layer management entity to request P2P operations:
These are the main callback functions for P2P module to provide event notifications to the upper layer management entity:
The P2P module uses following functions to request lower layer driver operations:
Events from lower layer driver operations are delivered to the P2P module with following functions:
In addition to the per-device state, the P2P module maintains per-group state for group owners. This is initialized with a call to p2p_group_init() when a group is created and deinitialized with p2p_group_deinit(). The upper layer GO management entity uses following functions to interact with the P2P per-group state:
The P2P module will use following callback function to update P2P IE for GO Beacon and Probe Response frames:
The following driver wrapper functions are needed for P2P in addition to the standard station/AP mode operations when the P2P module resides within wpa_supplicant:
The following driver wrapper events are needed for P2P in addition to the standard station/AP mode events when the P2P module resides within wpa_supplicant:
This section shows an example sequence of operations that can be used to implement P2P device discovery and group formation. The function calls are described based on the P2P module API. The exact design for the glue code outside the P2P module depends on the architecture used in the system.
An upper layer management entity starts P2P device discovery by calling p2p_find(). The P2P module start the discovery by requesting a full scan to be completed by calling p2p_config::p2p_scan(). Results from the scan will be reported by calling p2p_scan_res_handler() and after last result, the scan result processing is terminated with a call to p2p_scan_res_handled(). The P2P peers that are found during the full scan are reported with the p2p_config::dev_found() callback.
After the full scan, P2P module start alternating between Listen and Search states until the device discovery operation times out or terminated, e.g., with a call to p2p_stop_find().
When going into the Listen state, the P2P module requests the driver to be configured to be awake on the listen channel with a call to p2p_config::start_listen(). The glue code using the P2P module may implement this, e.g., by using remain-on-channel low-level driver functionality for off-channel operation. Once the driver is available on the requested channel, notification of this is delivered by calling p2p_listen_cb(). The Probe Request frames that are received during the Listen period are delivered to the P2P module by calling p2p_config::p2p_probe_req_rx() and P2P module request a response to these to be sent by using p2p_config::send_probe_resp() callback function. If a group owner negotiation from another P2P device is received during the device discovery phase, that is indicated to the upper layer code with the p2p_config::go_neg_req_tx() callback.
The Search state is implemented by using the normal scan interface, i.e., the P2P module will call p2p_config::p2p_scan() just like in the full scan phase described. Similarly, scan results from the search operation will be delivered to the P2P module using the p2p_scan_res_handler() and p2p_scan_res_handled() functions.
Once the upper layer management entity has found a peer with which it wants to connect by forming a new group, it initiates group owner negotiation by calling p2p_connect(). Before doing this, the upper layer code is responsible for asking the user to provide the PIN to be used during the provisioning step with the peer or the push button press for PBC mode. The glue code will need to figure out the intended interface address for the group before group owner negotiation can be started.
Optional Provision Discovery mechanism can be used to request the peer to display a PIN for the local device to enter (and vice versa). Upper layer management entity can request the specific mechanism by calling p2p_prov_disc_req(). The response to this will be reported with the p2p_config::prov_disc_resp() callback. If the peer device started Provision Discovery, an accepted request will be reported with the p2p_config::prov_disc_req() callback. The P2P module will automatically accept the Provision Discovery for display and keypad methods, but it is up to the upper layer manegement entity to actually generate the PIN and to configure it with following p2p_connect() call to actually authorize the connection.
The P2P module will use p2p_config::send_action() callback to request lower layer code to transmit an Action frame during group owner negotiation. p2p_send_action_cb() is used to report the result of transmission. If the peer is not reachable, the P2P module will try to find it by alternating between Action frame send and Listen states. The Listen state for this phase will be used similarly to the Listen state during device discovery as described above.
Once the group owner negotiation has been completed, its results will be reported with the p2p_config::go_neg_completed() callback. The upper layer management code or the glue code using the P2P module API is responsible for creating a new group interface and starting provisioning step at this point by configuring WPS Registrar or Enrollee functionality based on the reported group owner negotiation results. The upper layer code is also responsible for timing out WPS provisioning if it cannot be completed in 15 seconds.
Successful completion of the WPS provisioning is reported with a call to p2p_wps_success_cb(). The P2P module will clear its group formation state at this point and allows new group formation attempts to be started. The upper layer management code is responsible for configuring the GO to accept associations from devices and the client to connect to the GO with the provisioned credentials. GO is also responsible for calling p2p_group_notif_formation_done() as described below.
If the WPS provisioning step fails or times out, this is reported with a call to p2p_group_formation_failed(). The P2P module will clear its group formation state at this point and allows new group formation attempts to be started. The upper layer management code is responsible for removing the group interface for the failed group.
P2P protocol includes service discovery functionality that can be used to discover which services are provided by the peers before forming a group. This leverages the Generic Advertisement Service (GAS) protocol from IEEE 802.11u and P2P vendor-specific contents inside the Native GAS messages.
The P2P module takes care of GAS encapsulation, fragmentation, and actual transmission and reception of the Action frames needed for service discovery. The user of the P2P module is responsible for providing P2P specific Service Request TLV(s) for queries and Service Response TLV(s) for responses.
Service discovery is implemented by processing pending queries as a part of the device discovery phase. p2p_sd_request() function is used to schedule service discovery queries to a specific peer or to all discovered peers. p2p_sd_cancel_request() can be used to cancel a scheduled query. Queries that are specific to a single peer will be removed automatically after the response has been received.
After the service discovery queries have been queued, device discovery is started with a call to p2p_find(). The pending service discovery queries are then sent whenever a peer is discovered during the find operation. Responses to the queries will be reported with the p2p_config::sd_response() callback.
The received service discovery requests will be indicated with the p2p_config::sd_request() callback. The response to the query is sent by calling p2p_sd_response().
P2P service discovery provides a mechanism to notify peers about changes in available services. This works by incrementing Service Update Indicator value whenever there is a change in the services. This value is included in all SD request and response frames. The value received from the peers will be included in the p2p_config::sd_request() and p2p_config::sd_response() callbacks. The value to be sent to the peers is incremented with a call to p2p_sd_service_update() whenever availibility of the local services changes.
This section describes how P2P module can be used for managing per-group information in a group owner. The function calls are described based on the P2P module API. The exact design for the glue code outside the P2P module depends on the architecture used in the system.
When a P2P group interface is created in group owner role, per-group data is initialized with p2p_group_init(). This call provides a pointer to the per-device P2P module context and configures the per-group operation. The configured p2p_group_config::ie_update() callback is used to set the initial P2P IE for Beacon and Probe Response frames in the group owner. The AP mode implementation may use this information to add IEs into the frames.
Once the group formation has been completed (or if it is skipped in case of manual group setup), p2p_group_notif_formation_done() is called. This will allow the P2P module to update the P2P IE for Beacon and Probe Response frames.
The SME/MLME code that managements IEEE 802.11 association processing needs to inform P2P module whenever a P2P client associates or disassociates with the group. This is done by calling p2p_group_notif_assoc() and p2p_group_notif_disassoc(). The P2P module manages a list of group members and updates the P2P Group Information subelement in the P2P IE based on the information from the P2P clients. The p2p_group_config::ie_update() callback is used whenever the P2P IE in Probe Response frames needs to be changed.
The SME/MLME code that takes care of replying to Probe Request frames can use p2p_group_match_dev_type() to check whether the Probe Request frame request a reply only from groups that include a specific device type in one of the clients or GO. A match will be reported if the Probe Request does not request a specific device type, so this function can be used to filter or received Probe Request frames and only the ones that result in non-zero return value need to be replied.
When the P2P group interface for GO role is removed, p2p_group_deinit() is used to deinitialize the per-group P2P module state.
wpa_supplicant control interface can be used to manage P2P functionality from an external program (e.g., a GUI or a system configuration manager). This interface can be used directly through the control interface backend mechanism (e.g., local domain sockets on Linux) or with help of wpa_cli (e.g., from a script).
The following P2P-related commands are available:
The following P2P-related events are used:
wpa_gui has an example implementation of a GUI that could be used to manage P2P operations. The P2P related functionality is contained mostly in wpa_supplicant/wpa_gui-qt4/peers.cpp and it shows how the control interface commands and events can be used.
wpa_cli can be used to control wpa_supplicant in interactive mode. The following sessions show examples of commands used for device discovery and group formation. The lines starting with "> " are commands from the user (followed by command result indication) and lines starting with "<2>" are event messages from wpa_supplicant.
P2P device "Wireless Client":
> p2p_find OK > <2>P2P-DEVICE-FOUND 02:40:61:c2:f3:b7 p2p_dev_addr=02:40:61:c2:f3:b7 pri_dev_type=1-0050F204-1 name='Wireless Client 2' config_methods=0x18c dev_capab=0x1 group_capab=0x0 <2>P2P-GO-NEG-REQUEST 02:40:61:c2:f3:b7 <2>P2P-GO-NEG-REQUEST 02:40:61:c2:f3:b7 > p2p_connect 02:40:61:c2:f3:b7 pbc OK <2>P2P-GO-NEG-SUCCESS <2>P2P-GROUP-FORMATION-SUCCESS <2>P2P-GROUP-STARTED sta0-p2p-0 client DIRECT-vM > interface Available interfaces: sta0-p2p-0 sta0 > p2p_group_remove sta0-p2p-0 <2>P2P-GROUP-REMOVED sta0-p2p-0 client OK > term OK
P2P device "Wireless Client2" (which ended up operating in GO role):
> p2p_find OK <2>P2P-DEVICE-FOUND 02:f0:bc:44:87:62 p2p_dev_addr=02:f0:bc:44:87:62 pri_dev_type=1-0050F204-1 name='Wireless Client' config_methods=0x18c dev_capab=0x1 group_capab=0x0 > p2p_connect 02:f0:bc:44:87:62 pbc OK <2>P2P-GO-NEG-SUCCESS <2>P2P-GROUP-FORMATION-SUCCESS <2>P2P-GROUP-STARTED sta1-p2p-0 GO DIRECT-vM > interface Available interfaces: sta1-p2p-0 sta1 > p2p_group_remove sta1-p2p-0 <2>P2P-GROUP-REMOVED sta1-p2p-0 GO OK > term OK
1.8.6
