xref: /linux/drivers/net/wireless/intel/iwlwifi/mei/iwl-mei.h (revision 9410645520e9b820069761f3450ef6661418e279)
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 
iwl_mei_is_connected(void)486 static inline bool iwl_mei_is_connected(void)
487 { return false; }
488 
iwl_mei_get_nvm(void)489 static inline struct iwl_mei_nvm *iwl_mei_get_nvm(void)
490 { return NULL; }
491 
iwl_mei_get_ownership(void)492 static inline int iwl_mei_get_ownership(void)
493 { return 0; }
494 
iwl_mei_set_rfkill_state(bool hw_rfkill,bool sw_rfkill)495 static inline void iwl_mei_set_rfkill_state(bool hw_rfkill, bool sw_rfkill)
496 {}
497 
iwl_mei_set_nic_info(const u8 * mac_address,const u8 * nvm_address)498 static inline void iwl_mei_set_nic_info(const u8 *mac_address, const u8 *nvm_address)
499 {}
500 
iwl_mei_set_country_code(u16 mcc)501 static inline void iwl_mei_set_country_code(u16 mcc)
502 {}
503 
iwl_mei_set_power_limit(const __le16 * power_limit)504 static inline void iwl_mei_set_power_limit(const __le16 *power_limit)
505 {}
506 
iwl_mei_register(void * priv,const struct iwl_mei_ops * ops)507 static inline int iwl_mei_register(void *priv,
508 				   const struct iwl_mei_ops *ops)
509 { return -EOPNOTSUPP; }
510 
iwl_mei_start_unregister(void)511 static inline void iwl_mei_start_unregister(void)
512 {}
513 
iwl_mei_unregister_complete(void)514 static inline void iwl_mei_unregister_complete(void)
515 {}
516 
iwl_mei_set_netdev(struct net_device * netdev)517 static inline void iwl_mei_set_netdev(struct net_device *netdev)
518 {}
519 
iwl_mei_tx_copy_to_csme(struct sk_buff * skb,unsigned int ivlen)520 static inline void iwl_mei_tx_copy_to_csme(struct sk_buff *skb,
521 					   unsigned int ivlen)
522 {}
523 
iwl_mei_host_associated(const struct iwl_mei_conn_info * conn_info,const struct iwl_mei_colloc_info * colloc_info)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 
iwl_mei_host_disassociated(void)528 static inline void iwl_mei_host_disassociated(void)
529 {}
530 
iwl_mei_device_state(bool up)531 static inline void iwl_mei_device_state(bool up)
532 {}
533 
iwl_mei_pldr_req(void)534 static inline int iwl_mei_pldr_req(void)
535 { return 0; }
536 
iwl_mei_alive_notif(bool success)537 static inline void iwl_mei_alive_notif(bool success)
538 {}
539 
540 #endif /* CONFIG_IWLMEI */
541 
542 #endif /* __iwl_mei_h__ */
543