aboutsummaryrefslogtreecommitdiffstats log msg author committer range
path: root/doc/p2p.doxygen
blob: f46d1b80a7ccc01d30aec493430e8b55d3d7076e (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471  /** \page p2p Wi-Fi Direct - P2P module 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 \ref src/p2p/p2p.h. Provisioning step of Group Formation is implemented using WPS (\ref src/wps/wps.h). 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. \section p2p_arch P2P architecture 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. \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, e.g., ath9k. The following diagram shows the main components related to P2P functionality in such an architecture. \image html p2p_arch.png "P2P module within wpa_supplicant" \image latex p2p_arch.eps "P2P module within wpa_supplicant" width=15cm \subsection p2p_arch_umac P2P architecture with UMAC 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). \image html p2p_arch2.png "P2P module in kernel \image latex p2p_arch2.eps "P2P module in kernel" width=15cm \section p2p_module P2P module 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). \image html p2p_sm.png "P2P module state machine" \image latex p2p_sm.eps "P2P module state machine" width=15cm \subsection p2p_module_api P2P module API 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 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: - \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: - \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: - \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: - \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 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: - \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: - \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: - \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: - \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 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 \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 \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 \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 \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 \ref p2p_listen_cb(). The Probe Request frames that are received during the Listen period are delivered to the P2P module by calling \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 \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 \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 \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 \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 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 \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 \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 \ref p2p_connect() call to actually authorize the connection. 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. \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 \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 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 \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 \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 \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. \section p2p_sd P2P service discovery 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. \subsection p2p_sd_query Quering services of peers Service discovery is implemented by processing pending queries as a 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. \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 \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 \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 \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 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 \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 \ref p2p_sd_service_update() whenever availability of the local services changes. \section p2p_go P2P group owner 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 \ref p2p_group_init(). This call provides a pointer to the per-device P2P module context and configures the 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), \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 \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 \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 \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 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, \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 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: - \ref ctrl_iface_P2P_FIND P2P_FIND - \ref ctrl_iface_P2P_STOP_FIND P2P_STOP_FIND - \ref ctrl_iface_P2P_CONNECT P2P_CONNECT - \ref ctrl_iface_P2P_LISTEN P2P_LISTEN - \ref ctrl_iface_P2P_GROUP_REMOVE P2P_GROUP_REMOVE - \ref ctrl_iface_P2P_GROUP_ADD P2P_GROUP_ADD - \ref ctrl_iface_P2P_PROV_DISC P2P_PROV_DISC - \ref ctrl_iface_P2P_SERV_DISC_REQ P2P_SERV_DISC_REQ - \ref ctrl_iface_P2P_SERV_DISC_CANCEL_REQ P2P_SERV_DISC_CANCEL_REQ - \ref ctrl_iface_P2P_SERV_DISC_RESP P2P_SERV_DISC_RESP - \ref ctrl_iface_P2P_SERVICE_UPDATE P2P_SERVICE_UPDATE - \ref ctrl_iface_P2P_SERV_DISC_EXTERNAL P2P_SERV_DISC_EXTERNAL - \ref ctrl_iface_P2P_REJECT P2P_REJECT - \ref ctrl_iface_P2P_INVITE P2P_INVITE The following P2P-related events are used: - \ref ctrl_iface_event_P2P_EVENT_DEVICE_FOUND P2P-DEVICE-FOUND - \ref ctrl_iface_event_P2P_EVENT_GO_NEG_REQUEST P2P-GO-NEG-REQUEST - \ref ctrl_iface_event_P2P_EVENT_GO_NEG_SUCCESS P2P-GO-NEG-SUCCESS - \ref ctrl_iface_event_P2P_EVENT_GO_NEG_FAILURE P2P-GO-NEG-FAILURE - \ref ctrl_iface_event_P2P_EVENT_GROUP_FORMATION_SUCCESS P2P-GROUP-FORMATION-SUCCESS - \ref ctrl_iface_event_P2P_EVENT_GROUP_FORMATION_FAILURE P2P-GROUP-FORMATION-FAILURE - \ref ctrl_iface_event_P2P_EVENT_GROUP_STARTED P2P-GROUP-STARTED - \ref ctrl_iface_event_P2P_EVENT_GROUP_REMOVED P2P-GROUP-REMOVED - \ref ctrl_iface_event_P2P_EVENT_PROV_DISC_SHOW_PIN P2P-PROV-DISC-SHOW-PIN - \ref ctrl_iface_event_P2P_EVENT_PROV_DISC_ENTER_PIN P2P-PROV-DISC-ENTER-PIN - \ref ctrl_iface_event_P2P_EVENT_SERV_DISC_REQ P2P-SERV-DISC-REQ - \ref ctrl_iface_event_P2P_EVENT_SERV_DISC_RESP P2P-SERV-DISC-RESP - \ref ctrl_iface_event_P2P_EVENT_INVITATION_RECEIVED P2P-INVITATION-RECEIVED - \ref ctrl_iface_event_P2P_EVENT_INVITATION_RESULT P2P-INVITATION-RESULT \subsection p2p_wpa_gui GUI example (wpa_gui) 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. \subsection p2p_wpa_cli wpa_cli example 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": \verbatim > 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 \endverbatim P2P device "Wireless Client2" (which ended up operating in GO role): \verbatim > 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 \endverbatim */