1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * Copyright (C) 2021-2024 Intel Corporation 4 */ 5 6 #ifndef __iwl_mei_h__ 7 #define __iwl_mei_h__ 8 9 #include <linux/if_ether.h> 10 #include <linux/skbuff.h> 11 #include <linux/ieee80211.h> 12 13 /** 14 * DOC: Introduction 15 * 16 * iwlmei is the kernel module that is in charge of the communication between 17 * the iwlwifi driver and the CSME firmware's WLAN driver. This communication 18 * uses the SAP protocol defined in another file. 19 * iwlwifi can request or release ownership on the WiFi device through iwlmei. 20 * iwlmei may notify iwlwifi about certain events: what filter iwlwifi should 21 * use to passthrough inbound packets to the CSME firmware for example. iwlmei 22 * may also use iwlwifi to send traffic. This means that we need communication 23 * from iwlmei to iwlwifi and the other way around. 24 */ 25 26 /** 27 * DOC: Life cycle 28 * 29 * iwlmei exports symbols that are needed by iwlwifi so that iwlmei will always 30 * be loaded when iwlwifi is alive. iwlwifi registers itself to iwlmei and 31 * provides the pointers to the functions that iwlmei calls whenever needed. 32 * iwlwifi calls iwlmei through direct and context-free function calls. 33 * It is assumed that only one device is accessible to the CSME firmware and 34 * under the scope of iwlmei so that it is valid not to have any context passed 35 * to iwlmei's functions. 36 * 37 * There are cases in which iwlmei can't access the CSME firmware, because the 38 * CSME firmware is undergoing a reset, or the mei bus decided to unbind the 39 * device. In those cases, iwlmei will need not to send requests over the mei 40 * bus. Instead, it needs to cache the requests from iwlwifi and fulfill them 41 * when the mei bus is available again. 42 * 43 * iwlmei can call iwlwifi as long as iwlwifi is registered to iwlmei. When 44 * iwlwifi goes down (the PCI device is unbound, or the iwlwifi is unloaded) 45 * iwlwifi needs to unregister from iwlmei. 46 */ 47 48 /** 49 * DOC: Memory layout 50 * 51 * Since iwlwifi calls iwlmei without any context, iwlmei needs to hold a 52 * global pointer to its data (which is in the mei client device's private 53 * data area). If there was no bind on the mei bus, this pointer is NULL and 54 * iwlmei knows not access to the CSME firmware upon requests from iwlwifi. 55 * 56 * iwlmei needs to cache requests from iwlwifi when there is no mei client 57 * device available (when iwlmei has been removed from the mei bus). In this 58 * case, all iwlmei's data that resides in the mei client device's private data 59 * area is unavailable. For this specific case, a separate caching area is 60 * needed. 61 */ 62 63 /** 64 * DOC: Concurrency 65 * 66 * iwlwifi can call iwlmei at any time. iwlmei will take care to synchronize 67 * the calls from iwlwifi with its internal flows. iwlwifi must not call iwlmei 68 * in flows that cannot sleep. Moreover, iwlwifi must not call iwlmei in flows 69 * that originated from iwlmei. 70 */ 71 72 /** 73 * DOC: Probe and remove from mei bus driver 74 * 75 * When the mei bus driver enumerates its devices, it calls the iwlmei's probe 76 * function which will send the %SAP_ME_MSG_START message. The probe completes 77 * before the response (%SAP_ME_MSG_START_OK) is received. This response will 78 * be handle by the Rx path. Once it arrives, the connection to the CSME 79 * firmware is considered established and iwlwifi's requests can be treated 80 * against the CSME firmware. 81 * 82 * When the mei bus driver removes the device, iwlmei loses all the data that 83 * was attached to the mei client device. It clears the global pointer to the 84 * mei client device since it is not available anymore. This will cause all the 85 * requests coming from iwlwifi to be cached. This flow takes the global mutex 86 * to be synchronized with all the requests coming from iwlwifi. 87 */ 88 89 /** 90 * DOC: Driver load when CSME owns the device 91 * 92 * When the driver (iwlwifi) is loaded while CSME owns the device, 93 * it'll ask CSME to release the device through HW registers. CSME 94 * will release the device only in the case that there is no connection 95 * through the mei bus. If there is a mei bus connection, CSME will refuse 96 * to release the ownership on the device through the HW registers. In that 97 * case, iwlwifi must first request ownership using the SAP protocol. 98 * 99 * Once iwlwifi will request ownership through the SAP protocol, CSME will 100 * grant the ownership on the device through the HW registers as well. 101 * In order to request ownership over SAP, we first need to have an interface 102 * which means that we need to register to mac80211. 103 * This can't happen before we get the NVM that contains all the capabilities 104 * of the device. Reading the NVM usually requires the load the firmware, but 105 * this is impossible as long as we don't have ownership on the device. 106 * In order to solve this chicken and egg problem, the host driver can get 107 * the NVM through CSME which owns the device. It can send 108 * %SAP_MSG_NOTIF_GET_NVM, which will be replied by %SAP_MSG_NOTIF_NVM with 109 * the NVM's content that the host driver needs. 110 */ 111 112 /** 113 * DOC: CSME behavior regarding the ownership requests 114 * 115 * The ownership requests from the host can come in two different ways: 116 * - the HW registers in iwl_pcie_set_hw_ready 117 * - using the Software Arbitration Protocol (SAP) 118 * 119 * The host can ask CSME who owns the device with %SAP_MSG_NOTIF_WHO_OWNS_NIC, 120 * and it can request ownership with %SAP_MSG_NOTIF_HOST_ASKS_FOR_NIC_OWNERSHIP. 121 * The host will first use %SAP_MSG_NOTIF_WHO_OWNS_NIC to know what state 122 * CSME is in. In case CSME thinks it owns the device, the host can ask for 123 * ownership with %SAP_MSG_NOTIF_HOST_ASKS_FOR_NIC_OWNERSHIP. 124 * 125 * Here the table that describes CSME's behavior upon ownership request: 126 * 127 * +-------------------+------------+--------------+-----------------------------+------------+ 128 * | State | HW reg bit | Reply for | Event | HW reg bit | 129 * | | before | WHO_OWNS_NIC | | after | 130 * +===================+============+==============+=============================+============+ 131 * | WiAMT not | 0 | Host | HW register or | 0 | 132 * | operational | Host owner | | HOST_ASKS_FOR_NIC_OWNERSHIP | Host owner | 133 * +-------------------+------------+--------------+-----------------------------+------------+ 134 * | Operational & | 1 | N/A | HW register | 0 | 135 * | SAP down & | CSME owner | | | Host owner | 136 * | no session active | | | | | 137 * +-------------------+------------+--------------+-----------------------------+------------+ 138 * | Operational & | 1 | CSME | HW register | 1 | 139 * | SAP up | CSME owner | | | CSME owner | 140 * +-------------------+------------+--------------+-----------------------------+------------+ 141 * | Operational & | 1 | CSME | HOST_ASKS_FOR_NIC_OWNERSHIP | 0 | 142 * | SAP up | CSME owner | | | Host owner | 143 * +-------------------+------------+--------------+-----------------------------+------------+ 144 */ 145 146 /** 147 * DOC: Driver load when CSME is associated and a session is active 148 * 149 * A "session" is active when CSME is associated to an access point and the 150 * link is used to attach a remote driver or to control the system remotely. 151 * When a session is active, we want to make sure it won't disconnect when we 152 * take ownership on the device. 153 * In this case, the driver can get the device, but it'll need to make 154 * sure that it'll connect to the exact same AP (same BSSID). 155 * In order to do so, CSME will send the connection parameters through 156 * SAP and then the host can check if it can connect to this same AP. 157 * If yes, it can request ownership through SAP and connect quickly without 158 * scanning all the channels, but just probing the AP on the channel that 159 * CSME was connected to. 160 * In order to signal this specific scenario to iwlwifi, iwlmei will 161 * immediately require iwlwifi to report RF-Kill to the network stack. This 162 * RF-Kill will prevent the stack from getting the device, and it has a reason 163 * that tells the userspace that the device is in RF-Kill because it is not 164 * owned by the host. Once the userspace has configured the right profile, 165 * it'll be able to let iwlmei know that it can request ownership over SAP 166 * which will remove the RF-Kill, and finally allow the host to connect. 167 * The host has then 3 seconds to connect (including DHCP). Had the host 168 * failed to connect within those 3 seconds, CSME will take the device back. 169 */ 170 171 /** 172 * DOC: Datapath 173 * 174 * CSME can transmit packets, through the netdev that it gets from the wifi 175 * driver. It'll send packet in the 802.3 format and simply call 176 * dev_queue_xmit. 177 * 178 * For Rx, iwlmei registers a Rx handler that it attaches to the netdev. iwlmei 179 * may catch packets and send them to CSME, it can then either drop them so 180 * that they are invisible to user space, or let them go the user space. 181 * 182 * Packets transmitted by the user space do not need to be forwarded to CSME 183 * with the exception of the DHCP request. In order to know what IP is used 184 * by the user space, CSME needs to get the DHCP request. See 185 * iwl_mei_tx_copy_to_csme(). 186 */ 187 188 /** 189 * enum iwl_mei_nvm_caps - capabilities for MEI NVM 190 * @MEI_NVM_CAPS_LARI_SUPPORT: Lari is supported 191 * @MEI_NVM_CAPS_11AX_SUPPORT: 11AX is supported 192 */ 193 enum iwl_mei_nvm_caps { 194 MEI_NVM_CAPS_LARI_SUPPORT = BIT(0), 195 MEI_NVM_CAPS_11AX_SUPPORT = BIT(1), 196 }; 197 198 /** 199 * struct iwl_mei_nvm - used to pass the NVM from CSME 200 * @hw_addr: The MAC address 201 * @n_hw_addrs: The number of MAC addresses 202 * @reserved: For alignment. 203 * @radio_cfg: The radio configuration. 204 * @caps: See &enum iwl_mei_nvm_caps. 205 * @nvm_version: The version of the NVM. 206 * @channels: The data for each channel. 207 * 208 * If a field is added, it must correspond to the SAP structure. 209 */ 210 struct iwl_mei_nvm { 211 u8 hw_addr[ETH_ALEN]; 212 u8 n_hw_addrs; 213 u8 reserved; 214 u32 radio_cfg; 215 u32 caps; 216 u32 nvm_version; 217 u32 channels[110]; 218 }; 219 220 /** 221 * enum iwl_mei_pairwise_cipher - cipher for UCAST key 222 * @IWL_MEI_CIPHER_NONE: none 223 * @IWL_MEI_CIPHER_TKIP: tkip 224 * @IWL_MEI_CIPHER_CCMP: ccmp 225 * @IWL_MEI_CIPHER_GCMP: gcmp 226 * @IWL_MEI_CIPHER_GCMP_256: gcmp 256 227 * 228 * Note that those values are dictated by the CSME firmware API (see sap.h) 229 */ 230 enum iwl_mei_pairwise_cipher { 231 IWL_MEI_CIPHER_NONE = 0, 232 IWL_MEI_CIPHER_TKIP = 2, 233 IWL_MEI_CIPHER_CCMP = 4, 234 IWL_MEI_CIPHER_GCMP = 8, 235 IWL_MEI_CIPHER_GCMP_256 = 9, 236 }; 237 238 /** 239 * enum iwl_mei_akm_auth - a combination of AKM and AUTH method 240 * @IWL_MEI_AKM_AUTH_OPEN: No encryption 241 * @IWL_MEI_AKM_AUTH_RSNA: 1X profile 242 * @IWL_MEI_AKM_AUTH_RSNA_PSK: PSK profile 243 * @IWL_MEI_AKM_AUTH_SAE: SAE profile 244 * 245 * Note that those values are dictated by the CSME firmware API (see sap.h) 246 */ 247 enum iwl_mei_akm_auth { 248 IWL_MEI_AKM_AUTH_OPEN = 0, 249 IWL_MEI_AKM_AUTH_RSNA = 6, 250 IWL_MEI_AKM_AUTH_RSNA_PSK = 7, 251 IWL_MEI_AKM_AUTH_SAE = 9, 252 }; 253 254 /** 255 * struct iwl_mei_conn_info - connection info 256 * @lp_state: link protection state 257 * @auth_mode: authentication mode 258 * @ssid_len: the length of SSID 259 * @ssid: the SSID 260 * @pairwise_cipher: the cipher used for unicast packets 261 * @channel: the associated channel 262 * @band: the associated band 263 * @bssid: the BSSID 264 */ 265 struct iwl_mei_conn_info { 266 u8 lp_state; 267 u8 auth_mode; 268 u8 ssid_len; 269 u8 channel; 270 u8 band; 271 u8 pairwise_cipher; 272 u8 bssid[ETH_ALEN]; 273 u8 ssid[IEEE80211_MAX_SSID_LEN]; 274 }; 275 276 /** 277 * struct iwl_mei_colloc_info - collocated AP info 278 * @channel: the channel of the collocated AP 279 * @bssid: the BSSID of the collocated AP 280 */ 281 struct iwl_mei_colloc_info { 282 u8 channel; 283 u8 bssid[ETH_ALEN]; 284 }; 285 286 /** 287 * enum iwl_mei_sap_version - SAP version 288 * @IWL_MEI_SAP_VERSION_3: SAP version 3 289 * @IWL_MEI_SAP_VERSION_4: SAP version 4 290 */ 291 enum iwl_mei_sap_version { 292 IWL_MEI_SAP_VERSION_3 = 3, 293 IWL_MEI_SAP_VERSION_4 = 4, 294 }; 295 296 /* 297 * struct iwl_mei_ops - driver's operations called by iwlmei 298 * Operations will not be called more than once concurrently. 299 * It's not allowed to call iwlmei functions from this context. 300 * 301 * @me_conn_status: provide information about CSME's current connection. 302 * @rfkill: called when the wifi driver should report a change in the rfkill 303 * status. 304 * @roaming_forbidden: indicates whether roaming is forbidden. 305 * @sap_connected: indicate that SAP is now connected. Will be called in case 306 * the wifi driver registered to iwlmei before SAP connection succeeded or 307 * when the SAP connection is re-established. 308 * @nic_stolen: this means that device is no longer available. The device can 309 * still be used until the callback returns. 310 */ 311 struct iwl_mei_ops { 312 void (*me_conn_status)(void *priv, 313 const struct iwl_mei_conn_info *conn_info); 314 void (*rfkill)(void *priv, bool blocked, bool csme_taking_ownership); 315 void (*roaming_forbidden)(void *priv, bool forbidden); 316 void (*sap_connected)(void *priv); 317 void (*nic_stolen)(void *priv); 318 }; 319 320 #if IS_ENABLED(CONFIG_IWLMEI) 321 322 /** 323 * iwl_mei_is_connected() - is the connection to the CSME firmware established? 324 * 325 * Return: true if we have a SAP connection 326 */ 327 bool iwl_mei_is_connected(void); 328 329 /** 330 * iwl_mei_get_nvm() - returns the NVM for the device 331 * 332 * It is the caller's responsibility to free the memory returned 333 * by this function. 334 * This function blocks (sleeps) until the NVM is ready. 335 * 336 * Return: the NVM as received from CSME 337 */ 338 struct iwl_mei_nvm *iwl_mei_get_nvm(void); 339 340 /** 341 * iwl_mei_get_ownership() - request ownership 342 * 343 * This function blocks until ownership is granted or timeout expired. 344 * 345 * Return: 0 in case we could get ownership on the device 346 */ 347 int iwl_mei_get_ownership(void); 348 349 /** 350 * iwl_mei_set_rfkill_state() - set SW and HW RF kill states 351 * @hw_rfkill: HW RF kill state. 352 * @sw_rfkill: SW RF kill state. 353 * 354 * This function must be called when SW RF kill is issued by the user. 355 */ 356 void iwl_mei_set_rfkill_state(bool hw_rfkill, bool sw_rfkill); 357 358 /** 359 * iwl_mei_set_nic_info() - set mac address 360 * @mac_address: mac address to set 361 * @nvm_address: NVM mac address to set 362 * 363 * This function must be called upon mac address change. 364 */ 365 void iwl_mei_set_nic_info(const u8 *mac_address, const u8 *nvm_address); 366 367 /** 368 * iwl_mei_set_country_code() - set new country code 369 * @mcc: the new applied MCC 370 * 371 * This function must be called upon country code update 372 */ 373 void iwl_mei_set_country_code(u16 mcc); 374 375 /** 376 * iwl_mei_set_power_limit() - set TX power limit 377 * @power_limit: pointer to an array of 10 elements (le16) represents the power 378 * restrictions per chain. 379 * 380 * This function must be called upon power restrictions change 381 */ 382 void iwl_mei_set_power_limit(const __le16 *power_limit); 383 384 /** 385 * iwl_mei_register() - register the wifi driver to iwlmei 386 * @priv: a pointer to the wifi driver's context. Cannot be NULL. 387 * @ops: the ops structure. 388 * 389 * Return: 0 unless something went wrong. It is illegal to call any 390 * other API function before this function is called and succeeds. 391 * 392 * Only one wifi driver instance (wifi device instance really) 393 * can register at a time. 394 */ 395 int iwl_mei_register(void *priv, const struct iwl_mei_ops *ops); 396 397 /** 398 * iwl_mei_start_unregister() - unregister the wifi driver from iwlmei 399 * 400 * From this point on, iwlmei will not used the callbacks provided by 401 * the driver, but the device is still usable. 402 */ 403 void iwl_mei_start_unregister(void); 404 405 /** 406 * iwl_mei_unregister_complete() - complete the unregistration 407 * 408 * Must be called after iwl_mei_start_unregister. When this function returns, 409 * the device is owned by CSME. 410 */ 411 void iwl_mei_unregister_complete(void); 412 413 /** 414 * iwl_mei_set_netdev() - sets the netdev for Tx / Rx. 415 * @netdev: the net_device 416 * 417 * The caller should set the netdev to a non-NULL value when the 418 * interface is added. Packets might be sent to the driver immediately 419 * afterwards. 420 * The caller should set the netdev to NULL when the interface is removed. 421 * This function will call synchronize_net() after setting the netdev to NULL. 422 * Only when this function returns, can the caller assume that iwlmei will 423 * no longer inject packets into the netdev's Tx path. 424 * 425 * Context: This function can sleep and assumes rtnl_lock is taken. 426 * The netdev must be set to NULL before iwl_mei_start_unregister() is called. 427 */ 428 void iwl_mei_set_netdev(struct net_device *netdev); 429 430 /** 431 * iwl_mei_tx_copy_to_csme() - must be called for each packet sent by 432 * the wifi driver. 433 * @skb: the skb sent 434 * @ivlen: the size of the IV that needs to be skipped after the MAC and 435 * before the SNAP header. 436 * 437 * This function doesn't take any lock, it simply tries to catch DHCP 438 * packets sent by the wifi driver. If the packet is a DHCP packet, it 439 * will send it to CSME. This function must not be called for virtual 440 * interfaces that are not monitored by CSME, meaning it must be called 441 * only for packets transmitted by the netdevice that was registered 442 * with iwl_mei_set_netdev(). 443 */ 444 void iwl_mei_tx_copy_to_csme(struct sk_buff *skb, unsigned int ivlen); 445 446 /** 447 * iwl_mei_host_associated() - must be called when iwlwifi associated. 448 * @conn_info: pointer to the connection info structure. 449 * @colloc_info: pointer to the collocated AP info. This is relevant only in 450 * case of UHB associated AP, otherwise set to NULL. 451 */ 452 void iwl_mei_host_associated(const struct iwl_mei_conn_info *conn_info, 453 const struct iwl_mei_colloc_info *colloc_info); 454 455 /** 456 * iwl_mei_host_disassociated() - must be called when iwlwifi disassociated. 457 */ 458 void iwl_mei_host_disassociated(void); 459 460 /** 461 * iwl_mei_device_state() - must be called when the device changes up/down state 462 * @up: true if the device is up, false otherwise. 463 */ 464 void iwl_mei_device_state(bool up); 465 466 /** 467 * iwl_mei_pldr_req() - must be called before loading the fw 468 * 469 * Requests from the ME that it releases its potential bus access to 470 * the WiFi NIC so that the device can safely undergo product reset. 471 * 472 * Return: 0 if the request was successful and the device can be 473 * reset, a negative error value otherwise 474 */ 475 int iwl_mei_pldr_req(void); 476 477 /** 478 * iwl_mei_alive_notif() - must be called when alive notificaiton is received 479 * @success: true if received alive notification, false if waiting for the 480 * notificaiton timed out. 481 */ 482 void iwl_mei_alive_notif(bool success); 483 484 #else 485 486 static inline bool iwl_mei_is_connected(void) 487 { return false; } 488 489 static inline struct iwl_mei_nvm *iwl_mei_get_nvm(void) 490 { return NULL; } 491 492 static inline int iwl_mei_get_ownership(void) 493 { return 0; } 494 495 static inline void iwl_mei_set_rfkill_state(bool hw_rfkill, bool sw_rfkill) 496 {} 497 498 static inline void iwl_mei_set_nic_info(const u8 *mac_address, const u8 *nvm_address) 499 {} 500 501 static inline void iwl_mei_set_country_code(u16 mcc) 502 {} 503 504 static inline void iwl_mei_set_power_limit(const __le16 *power_limit) 505 {} 506 507 static inline int iwl_mei_register(void *priv, 508 const struct iwl_mei_ops *ops) 509 { return -EOPNOTSUPP; } 510 511 static inline void iwl_mei_start_unregister(void) 512 {} 513 514 static inline void iwl_mei_unregister_complete(void) 515 {} 516 517 static inline void iwl_mei_set_netdev(struct net_device *netdev) 518 {} 519 520 static inline void iwl_mei_tx_copy_to_csme(struct sk_buff *skb, 521 unsigned int ivlen) 522 {} 523 524 static inline void iwl_mei_host_associated(const struct iwl_mei_conn_info *conn_info, 525 const struct iwl_mei_colloc_info *colloc_info) 526 {} 527 528 static inline void iwl_mei_host_disassociated(void) 529 {} 530 531 static inline void iwl_mei_device_state(bool up) 532 {} 533 534 static inline int iwl_mei_pldr_req(void) 535 { return 0; } 536 537 static inline void iwl_mei_alive_notif(bool success) 538 {} 539 540 #endif /* CONFIG_IWLMEI */ 541 542 #endif /* __iwl_mei_h__ */ 543