543 lines · c
1/* SPDX-License-Identifier: GPL-2.0-only */2/*3 * Copyright (C) 2021-2024 Intel Corporation4 */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: Introduction15 *16 * iwlmei is the kernel module that is in charge of the communication between17 * the iwlwifi driver and the CSME firmware's WLAN driver. This communication18 * 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 should21 * use to passthrough inbound packets to the CSME firmware for example. iwlmei22 * may also use iwlwifi to send traffic. This means that we need communication23 * from iwlmei to iwlwifi and the other way around.24 */25 26/**27 * DOC: Life cycle28 *29 * iwlmei exports symbols that are needed by iwlwifi so that iwlmei will always30 * be loaded when iwlwifi is alive. iwlwifi registers itself to iwlmei and31 * 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 and34 * under the scope of iwlmei so that it is valid not to have any context passed35 * to iwlmei's functions.36 *37 * There are cases in which iwlmei can't access the CSME firmware, because the38 * CSME firmware is undergoing a reset, or the mei bus decided to unbind the39 * device. In those cases, iwlmei will need not to send requests over the mei40 * bus. Instead, it needs to cache the requests from iwlwifi and fulfill them41 * when the mei bus is available again.42 *43 * iwlmei can call iwlwifi as long as iwlwifi is registered to iwlmei. When44 * 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 layout50 *51 * Since iwlwifi calls iwlmei without any context, iwlmei needs to hold a52 * global pointer to its data (which is in the mei client device's private53 * data area). If there was no bind on the mei bus, this pointer is NULL and54 * 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 client57 * device available (when iwlmei has been removed from the mei bus). In this58 * case, all iwlmei's data that resides in the mei client device's private data59 * area is unavailable. For this specific case, a separate caching area is60 * needed.61 */62 63/**64 * DOC: Concurrency65 *66 * iwlwifi can call iwlmei at any time. iwlmei will take care to synchronize67 * the calls from iwlwifi with its internal flows. iwlwifi must not call iwlmei68 * in flows that cannot sleep. Moreover, iwlwifi must not call iwlmei in flows69 * that originated from iwlmei.70 */71 72/**73 * DOC: Probe and remove from mei bus driver74 *75 * When the mei bus driver enumerates its devices, it calls the iwlmei's probe76 * function which will send the %SAP_ME_MSG_START message. The probe completes77 * before the response (%SAP_ME_MSG_START_OK) is received. This response will78 * be handle by the Rx path. Once it arrives, the connection to the CSME79 * firmware is considered established and iwlwifi's requests can be treated80 * against the CSME firmware.81 *82 * When the mei bus driver removes the device, iwlmei loses all the data that83 * was attached to the mei client device. It clears the global pointer to the84 * mei client device since it is not available anymore. This will cause all the85 * requests coming from iwlwifi to be cached. This flow takes the global mutex86 * to be synchronized with all the requests coming from iwlwifi.87 */88 89/**90 * DOC: Driver load when CSME owns the device91 *92 * When the driver (iwlwifi) is loaded while CSME owns the device,93 * it'll ask CSME to release the device through HW registers. CSME94 * will release the device only in the case that there is no connection95 * through the mei bus. If there is a mei bus connection, CSME will refuse96 * to release the ownership on the device through the HW registers. In that97 * case, iwlwifi must first request ownership using the SAP protocol.98 *99 * Once iwlwifi will request ownership through the SAP protocol, CSME will100 * 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 interface102 * which means that we need to register to mac80211.103 * This can't happen before we get the NVM that contains all the capabilities104 * of the device. Reading the NVM usually requires the load the firmware, but105 * 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 get107 * the NVM through CSME which owns the device. It can send108 * %SAP_MSG_NOTIF_GET_NVM, which will be replied by %SAP_MSG_NOTIF_NVM with109 * the NVM's content that the host driver needs.110 */111 112/**113 * DOC: CSME behavior regarding the ownership requests114 *115 * The ownership requests from the host can come in two different ways:116 * - the HW registers in iwl_pcie_set_hw_ready117 * - 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 state122 * CSME is in. In case CSME thinks it owns the device, the host can ask for123 * 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 active148 *149 * A "session" is active when CSME is associated to an access point and the150 * 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 we152 * take ownership on the device.153 * In this case, the driver can get the device, but it'll need to make154 * sure that it'll connect to the exact same AP (same BSSID).155 * In order to do so, CSME will send the connection parameters through156 * 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 without158 * scanning all the channels, but just probing the AP on the channel that159 * CSME was connected to.160 * In order to signal this specific scenario to iwlwifi, iwlmei will161 * immediately require iwlwifi to report RF-Kill to the network stack. This162 * RF-Kill will prevent the stack from getting the device, and it has a reason163 * that tells the userspace that the device is in RF-Kill because it is not164 * 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 SAP166 * 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 host168 * failed to connect within those 3 seconds, CSME will take the device back.169 */170 171/**172 * DOC: Datapath173 *174 * CSME can transmit packets, through the netdev that it gets from the wifi175 * driver. It'll send packet in the 802.3 format and simply call176 * dev_queue_xmit.177 *178 * For Rx, iwlmei registers a Rx handler that it attaches to the netdev. iwlmei179 * may catch packets and send them to CSME, it can then either drop them so180 * 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 CSME183 * with the exception of the DHCP request. In order to know what IP is used184 * by the user space, CSME needs to get the DHCP request. See185 * iwl_mei_tx_copy_to_csme().186 */187 188/**189 * enum iwl_mei_nvm_caps - capabilities for MEI NVM190 * @MEI_NVM_CAPS_LARI_SUPPORT: Lari is supported191 * @MEI_NVM_CAPS_11AX_SUPPORT: 11AX is supported192 */193enum 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 CSME200 * @hw_addr: The MAC address201 * @n_hw_addrs: The number of MAC addresses202 * @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 */210struct 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 key222 * @IWL_MEI_CIPHER_NONE: none223 * @IWL_MEI_CIPHER_TKIP: tkip224 * @IWL_MEI_CIPHER_CCMP: ccmp225 * @IWL_MEI_CIPHER_GCMP: gcmp226 * @IWL_MEI_CIPHER_GCMP_256: gcmp 256227 *228 * Note that those values are dictated by the CSME firmware API (see sap.h)229 */230enum 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 method240 * @IWL_MEI_AKM_AUTH_OPEN: No encryption241 * @IWL_MEI_AKM_AUTH_RSNA: 1X profile242 * @IWL_MEI_AKM_AUTH_RSNA_PSK: PSK profile243 * @IWL_MEI_AKM_AUTH_SAE: SAE profile244 *245 * Note that those values are dictated by the CSME firmware API (see sap.h)246 */247enum 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 info256 * @lp_state: link protection state257 * @auth_mode: authentication mode258 * @ssid_len: the length of SSID259 * @ssid: the SSID260 * @pairwise_cipher: the cipher used for unicast packets261 * @channel: the associated channel262 * @band: the associated band263 * @bssid: the BSSID264 */265struct 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 info278 * @channel: the channel of the collocated AP279 * @bssid: the BSSID of the collocated AP280 */281struct iwl_mei_colloc_info {282 u8 channel;283 u8 bssid[ETH_ALEN];284};285 286/**287 * enum iwl_mei_sap_version - SAP version288 * @IWL_MEI_SAP_VERSION_3: SAP version 3289 * @IWL_MEI_SAP_VERSION_4: SAP version 4290 */291enum 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 iwlmei298 * 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 rfkill303 * status.304 * @roaming_forbidden: indicates whether roaming is forbidden.305 * @sap_connected: indicate that SAP is now connected. Will be called in case306 * the wifi driver registered to iwlmei before SAP connection succeeded or307 * when the SAP connection is re-established.308 * @nic_stolen: this means that device is no longer available. The device can309 * still be used until the callback returns.310 */311struct 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 connection326 */327bool iwl_mei_is_connected(void);328 329/**330 * iwl_mei_get_nvm() - returns the NVM for the device331 *332 * It is the caller's responsibility to free the memory returned333 * by this function.334 * This function blocks (sleeps) until the NVM is ready.335 *336 * Return: the NVM as received from CSME337 */338struct iwl_mei_nvm *iwl_mei_get_nvm(void);339 340/**341 * iwl_mei_get_ownership() - request ownership342 *343 * This function blocks until ownership is granted or timeout expired.344 *345 * Return: 0 in case we could get ownership on the device346 */347int iwl_mei_get_ownership(void);348 349/**350 * iwl_mei_set_rfkill_state() - set SW and HW RF kill states351 * @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 */356void iwl_mei_set_rfkill_state(bool hw_rfkill, bool sw_rfkill);357 358/**359 * iwl_mei_set_nic_info() - set mac address360 * @mac_address: mac address to set361 * @nvm_address: NVM mac address to set362 *363 * This function must be called upon mac address change.364 */365void iwl_mei_set_nic_info(const u8 *mac_address, const u8 *nvm_address);366 367/**368 * iwl_mei_set_country_code() - set new country code369 * @mcc: the new applied MCC370 *371 * This function must be called upon country code update372 */373void iwl_mei_set_country_code(u16 mcc);374 375/**376 * iwl_mei_set_power_limit() - set TX power limit377 * @power_limit: pointer to an array of 10 elements (le16) represents the power378 * restrictions per chain.379 *380 * This function must be called upon power restrictions change381 */382void iwl_mei_set_power_limit(const __le16 *power_limit);383 384/**385 * iwl_mei_register() - register the wifi driver to iwlmei386 * @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 any390 * 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 */395int iwl_mei_register(void *priv, const struct iwl_mei_ops *ops);396 397/**398 * iwl_mei_start_unregister() - unregister the wifi driver from iwlmei399 *400 * From this point on, iwlmei will not used the callbacks provided by401 * the driver, but the device is still usable.402 */403void iwl_mei_start_unregister(void);404 405/**406 * iwl_mei_unregister_complete() - complete the unregistration407 *408 * Must be called after iwl_mei_start_unregister. When this function returns,409 * the device is owned by CSME.410 */411void iwl_mei_unregister_complete(void);412 413/**414 * iwl_mei_set_netdev() - sets the netdev for Tx / Rx.415 * @netdev: the net_device416 *417 * The caller should set the netdev to a non-NULL value when the418 * interface is added. Packets might be sent to the driver immediately419 * 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 will423 * 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 */428void iwl_mei_set_netdev(struct net_device *netdev);429 430/**431 * iwl_mei_tx_copy_to_csme() - must be called for each packet sent by432 * the wifi driver.433 * @skb: the skb sent434 * @ivlen: the size of the IV that needs to be skipped after the MAC and435 * before the SNAP header.436 *437 * This function doesn't take any lock, it simply tries to catch DHCP438 * packets sent by the wifi driver. If the packet is a DHCP packet, it439 * will send it to CSME. This function must not be called for virtual440 * interfaces that are not monitored by CSME, meaning it must be called441 * only for packets transmitted by the netdevice that was registered442 * with iwl_mei_set_netdev().443 */444void 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 in450 * case of UHB associated AP, otherwise set to NULL.451 */452void 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 */458void iwl_mei_host_disassociated(void);459 460/**461 * iwl_mei_device_state() - must be called when the device changes up/down state462 * @up: true if the device is up, false otherwise.463 */464void iwl_mei_device_state(bool up);465 466/**467 * iwl_mei_pldr_req() - must be called before loading the fw468 *469 * Requests from the ME that it releases its potential bus access to470 * 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 be473 * reset, a negative error value otherwise474 */475int iwl_mei_pldr_req(void);476 477/**478 * iwl_mei_alive_notif() - must be called when alive notificaiton is received479 * @success: true if received alive notification, false if waiting for the480 * notificaiton timed out.481 */482void iwl_mei_alive_notif(bool success);483 484#else485 486static inline bool iwl_mei_is_connected(void)487{ return false; }488 489static inline struct iwl_mei_nvm *iwl_mei_get_nvm(void)490{ return NULL; }491 492static inline int iwl_mei_get_ownership(void)493{ return 0; }494 495static inline void iwl_mei_set_rfkill_state(bool hw_rfkill, bool sw_rfkill)496{}497 498static inline void iwl_mei_set_nic_info(const u8 *mac_address, const u8 *nvm_address)499{}500 501static inline void iwl_mei_set_country_code(u16 mcc)502{}503 504static inline void iwl_mei_set_power_limit(const __le16 *power_limit)505{}506 507static inline int iwl_mei_register(void *priv,508 const struct iwl_mei_ops *ops)509{ return -EOPNOTSUPP; }510 511static inline void iwl_mei_start_unregister(void)512{}513 514static inline void iwl_mei_unregister_complete(void)515{}516 517static inline void iwl_mei_set_netdev(struct net_device *netdev)518{}519 520static inline void iwl_mei_tx_copy_to_csme(struct sk_buff *skb,521 unsigned int ivlen)522{}523 524static 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 528static inline void iwl_mei_host_disassociated(void)529{}530 531static inline void iwl_mei_device_state(bool up)532{}533 534static inline int iwl_mei_pldr_req(void)535{ return 0; }536 537static inline void iwl_mei_alive_notif(bool success)538{}539 540#endif /* CONFIG_IWLMEI */541 542#endif /* __iwl_mei_h__ */543