@ -3,7 +3,7 @@
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,
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.
@ -19,16 +19,16 @@ 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
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.
\ref src/p2p/p2p.h.
Provisioning step of Group Formation is implemented using WPS
(src/wps/wps.h).
(\ref 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
wpa_supplicant includes code in interact with both the P2P module
(\ref wpa_supplicant/p2p_supplicant.c) and WPS
(\ref 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.
@ -48,7 +48,7 @@ functionality.
\subsection p2p_arch_mac80211 P2P architecture with Linux/mac80211/ath9k
An architecture where the P2P module resides inside the
% wpa_supplicant process is used with Linux mac80211-based drivers,
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.
@ -82,7 +82,7 @@ and the alternating Listen and Search states within Find).
\subsection p2p_module_api P2P module API
P2P module API is defined in src/p2p/p2p.h. The API consists of
P2P module API is defined in \ref 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
@ -92,51 +92,51 @@ used for P2P related operations.
These are the main functions for an upper layer management entity to
request P2P operations:
- p2p_find()
- p2p_stop_find()
- p2p_listen()
- p2p_connect()
- p2p_reject()
- p2p_prov_disc_req()
- p2p_sd_request()
- p2p_sd_cancel_request()
- p2p_sd_response()
- p2p_sd_service_update()
- p2p_invite()
- \ref p2p_find()
- \ref p2p_stop_find()
- \ref p2p_listen()
- \ref p2p_connect()
- \ref p2p_reject()
- \ref p2p_prov_disc_req()
- \ref p2p_sd_request()
- \ref p2p_sd_cancel_request()
- \ref p2p_sd_response()
- \ref p2p_sd_service_update()
- \ref p2p_invite()
These are the main callback functions for P2P module to provide event
notifications to the upper layer management entity:
- p2p_config::dev_found()
- p2p_config::go_neg_req_rx()
- p2p_config::go_neg_completed()
- p2p_config::sd_request()
- p2p_config::sd_response()
- p2p_config::prov_disc_req()
- p2p_config::prov_disc_resp()
- p2p_config::invitation_process()
- p2p_config::invitation_received()
- p2p_config::invitation_result()
- \ref p2p_config::dev_found()
- \ref p2p_config::go_neg_req_rx()
- \ref p2p_config::go_neg_completed()
- \ref p2p_config::sd_request()
- \ref p2p_config::sd_response()
- \ref p2p_config::prov_disc_req()
- \ref p2p_config::prov_disc_resp()
- \ref p2p_config::invitation_process()
- \ref p2p_config::invitation_received()
- \ref p2p_config::invitation_result()
The P2P module uses following functions to request lower layer driver
operations:
- p2p_config::p2p_scan()
- p2p_config::send_probe_resp()
- p2p_config::send_action()
- p2p_config::send_action_done()
- p2p_config::start_listen()
- p2p_config::stop_listen()
- \ref p2p_config::p2p_scan()
- \ref p2p_config::send_probe_resp()
- \ref p2p_config::send_action()
- \ref p2p_config::send_action_done()
- \ref p2p_config::start_listen()
- \ref p2p_config::stop_listen()
Events from lower layer driver operations are delivered to the P2P
module with following functions:
- p2p_probe_req_rx()
- p2p_rx_action()
- p2p_scan_res_handler()
- p2p_scan_res_handled()
- p2p_send_action_cb()
- p2p_listen_cb()
- \ref p2p_probe_req_rx()
- \ref p2p_rx_action()
- \ref p2p_scan_res_handler()
- \ref p2p_scan_res_handled()
- \ref p2p_send_action_cb()
- \ref p2p_listen_cb()
In addition to the per-device state, the P2P module maintains
per-group state for group owners. This is initialized with a call to
@ -144,39 +144,36 @@ 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:
- p2p_group_notif_assoc()
- p2p_group_notif_disassoc()
- p2p_group_notif_formation_done()
- p2p_group_match_dev_type()
- \ref p2p_group_notif_assoc()
- \ref p2p_group_notif_disassoc()
- \ref p2p_group_notif_formation_done()
- \ref p2p_group_match_dev_type()
The P2P module will use following callback function to update P2P IE
for GO Beacon and Probe Response frames:
- p2p_group_config::ie_update()
- \ref p2p_group_config::ie_update()
\section p2p_driver P2P driver operations (low-level interface)
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:
- wpa_driver_ops::if_add()
- wpa_driver_ops::if_remove()
- wpa_driver_ops::alloc_interface_addr()
- wpa_driver_ops::release_interface_addr()
- wpa_driver_ops::remain_on_channel()
- wpa_driver_ops::cancel_remain_on_channel()
- wpa_driver_ops::send_action()
- wpa_driver_ops::probe_req_report()
- wpa_driver_ops::disable_11b_rates()
within wpa_supplicant:
- \ref wpa_driver_ops::if_add()
- \ref wpa_driver_ops::if_remove()
- \ref wpa_driver_ops::remain_on_channel()
- \ref wpa_driver_ops::cancel_remain_on_channel()
- \ref wpa_driver_ops::send_action()
- \ref wpa_driver_ops::probe_req_report()
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:
- wpa_event_type::EVENT_RX_ACTION
- wpa_event_type::EVENT_REMAIN_ON_CHANNEL
- wpa_event_type::EVENT_CANCEL_REMAIN_ON_CHANNEL
- wpa_event_type::EVENT_RX_PROBE_REQ
wpa_supplicant:
- \ref wpa_event_type::EVENT_RX_MGMT
- \ref wpa_event_type::EVENT_REMAIN_ON_CHANNEL
- \ref wpa_event_type::EVENT_CANCEL_REMAIN_ON_CHANNEL
- \ref wpa_event_type::EVENT_RX_PROBE_REQ
\section p2p_go_neg P2P device discovery and group formation
@ -188,40 +185,40 @@ 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
calling \ref p2p_find(). The P2P module start the discovery by requesting a
full scan to be completed by calling \ref p2p_config::p2p_scan(). Results
from the scan will be reported by calling \ref 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.
call to \ref p2p_scan_res_handled(). The P2P peers that are found during
the full scan are reported with the \ref 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().
terminated, e.g., with a call to \ref 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
\ref 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
\ref 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
\ref p2p_config::p2p_probe_req_rx() and P2P module request a response to
these to be sent by using \ref 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.
upper layer code with the \ref 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
i.e., the P2P module will call \ref 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.
\ref p2p_scan_res_handler() and \ref 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
negotiation by calling \ref 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
@ -231,25 +228,25 @@ 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
\ref p2p_prov_disc_req(). The response to this will be reported with the
\ref 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
\ref 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
generate the PIN and to configure it with following \ref p2p_connect() call
to actually authorize the connection.
The P2P module will use p2p_config::send_action() callback to request
The P2P module will use \ref 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
negotiation. \ref 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
be reported with the \ref 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
@ -258,15 +255,15 @@ 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
to \ref 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.
calling \ref 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
a call to \ref 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.
@ -289,23 +286,23 @@ Response TLV(s) for responses.
\subsection p2p_sd_query Quering services of peers
Service discovery is implemented by processing pending queries as a
part of the device discovery phase. p2p_sd_request() function is used
part of the device discovery phase. \ref 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
discovered peers. \ref 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
is started with a call to \ref 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.
\ref p2p_config::sd_response() callback.
\subsection p2p_sd_response Replying to service discovery queries from peers
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().
\ref p2p_config::sd_request() callback. The response to the query is sent
by calling \ref p2p_sd_response().
\subsection p2p_sd_indicator Service update indicator
@ -314,9 +311,9 @@ 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
\ref p2p_config::sd_request() and \ref 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
\ref p2p_sd_service_update() whenever availibility of the local services
changes.
@ -329,29 +326,29 @@ 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
data is initialized with \ref 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()
per-group operation. The configured \ref 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
case of manual group setup), \ref 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
\ref p2p_group_notif_assoc() and \ref 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
clients. The \ref 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
can use \ref 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
@ -359,13 +356,13 @@ 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
\ref p2p_group_deinit() is used to deinitialize the per-group P2P module
state.
\section p2p_ctrl_iface P2P control interface
% wpa_supplicant \ref ctrl_iface_page "control interface" can be used
wpa_supplicant \ref ctrl_iface_page "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
@ -414,11 +411,11 @@ control interface commands and events can be used.
\subsection p2p_wpa_cli wpa_cli example
wpa_cli can be used to control % wpa_supplicant in interactive
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.
lines starting with "<2>" are event messages from wpa_supplicant.
P2P device "Wireless Client":
Jouni Malinen
9 years ago