xref: /wlan-driver/qca-wifi-host-cmn/qdf/inc/qdf_platform.h (revision 5113495b16420b49004c444715d2daae2066e7dc)
1 /*
2  * Copyright (c) 2018-2021 The Linux Foundation. All rights reserved.
3  * Copyright (c) 2023-2024 Qualcomm Innovation Center, Inc. All rights reserved.
4  *
5  * Permission to use, copy, modify, and/or distribute this software for
6  * any purpose with or without fee is hereby granted, provided that the
7  * above copyright notice and this permission notice appear in all
8  * copies.
9  *
10  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12  * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13  * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15  * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17  * PERFORMANCE OF THIS SOFTWARE.
18  */
19 
20 /**
21  * DOC: qdf_platform.h
22  * This file defines platform API abstractions.
23  */
24 
25 #ifndef _QDF_PLATFORM_H
26 #define _QDF_PLATFORM_H
27 
28 #include "qdf_types.h"
29 
30 /**
31  * typedef qdf_self_recovery_callback() - callback for self recovery
32  * @psoc: pointer to the posc object
33  * @reason: the reason for the recovery request
34  * @func: the caller's function name
35  * @line: the line number of the callsite
36  *
37  * Return: none
38  */
39 typedef void (*qdf_self_recovery_callback)(void *psoc,
40 					   enum qdf_hang_reason reason,
41 					   const char *func,
42 					   const uint32_t line);
43 
44 /**
45  * typedef qdf_is_fw_down_callback() - callback to query if fw is down
46  *
47  * Return: true if fw is down and false if fw is not down
48  */
49 typedef bool (*qdf_is_fw_down_callback)(void);
50 
51 /**
52  * qdf_register_fw_down_callback() - API to register fw down callback
53  * @is_fw_down: callback to query if fw is down or not
54  *
55  * Return: none
56  */
57 void qdf_register_fw_down_callback(qdf_is_fw_down_callback is_fw_down);
58 
59 /**
60  * qdf_is_fw_down() - API to check if fw is down or not
61  *
62  * Return: true: if fw is down
63  *	   false: if fw is not down
64  */
65 bool qdf_is_fw_down(void);
66 
67 /**
68  * typedef qdf_wmi_recv_qmi_cb() - callback to receive WMI over QMI
69  * @cb_ctx: WMI event recv callback context(wmi_handle)
70  * @buf: WMI buffer
71  * @len: WMI buffer len
72  *
73  * Return: 0 if success otherwise -EINVAL
74  */
75 typedef int (*qdf_wmi_recv_qmi_cb)(void *cb_ctx, void *buf, int len);
76 
77 /**
78  * typedef qdf_qmi_ind_cb() - callback to receive QMI Indication
79  * @cb_ctx: QMI indication callback context
80  * @type: Indication type
81  * @event: Indication Event
82  * @event_len: QMI indication event buffer len
83  *
84  * Return: 0 if success otherwise -EINVAL
85  */
86 typedef int (*qdf_qmi_ind_cb)(void *cb_ctx, uint16_t type,
87 			      void *event, int event_len);
88 
89 /**
90  * typedef qdf_wmi_send_over_qmi_callback() - callback to send WMI over QMI
91  * @buf: WMI buffer
92  * @len: WMI buffer len
93  * @cb_ctx: WMI event recv callback context(wmi_handle)
94  * @wmi_rx_cb: WMI event receive call back
95  *
96  * Return: QDF_STATUS_SUCCESS if success otherwise QDF error code
97  */
98 typedef QDF_STATUS (*qdf_wmi_send_over_qmi_callback)(void *buf, uint32_t len,
99 						     void *cb_ctx,
100 						     qdf_wmi_recv_qmi_cb
101 						     wmi_rx_cb);
102 
103 /**
104  * typedef qdf_send_ind_over_qmi_callback() - callback to receive QMI Indication
105  * @cb_ctx: QMI Indication recv callback context
106  * @qmi_ind_cb: QMI Indication receive callback
107  *
108  * Return: QDF_STATUS_SUCCESS if success otherwise QDF error code
109  */
110 typedef QDF_STATUS (*qdf_send_ind_over_qmi_callback)(void *cb_ctx,
111 						     qdf_qmi_ind_cb qmi_ind_cb);
112 
113 /**
114  * qdf_register_wmi_send_recv_qmi_callback() - Register WMI over QMI callback
115  * @wmi_send_recv_qmi_cb: callback to send recv WMI data over QMI
116  *
117  * Return: none
118  */
119 void qdf_register_wmi_send_recv_qmi_callback(qdf_wmi_send_over_qmi_callback
120 					     wmi_send_recv_qmi_cb);
121 
122 /**
123  * qdf_register_qmi_indication_callback() - Register QMI Indication callback
124  * @qmi_ind_cb: callback to receive QMI Indications
125  *
126  * Return: none
127  */
128 void qdf_register_qmi_indication_callback(qdf_send_ind_over_qmi_callback qmi_ind_cb);
129 
130 /**
131  * qdf_wmi_send_recv_qmi() - API to send receive WMI data over QMI
132  * @buf: WMI buffer
133  * @len: WMI buffer len
134  * @cb_ctx: WMI event recv callback context(wmi_handle)
135  * @wmi_rx_cb: WMI event receive call back
136  *
137  * Return: QDF STATUS of operation
138  */
139 QDF_STATUS qdf_wmi_send_recv_qmi(void *buf, uint32_t len, void *cb_ctx,
140 				 qdf_wmi_recv_qmi_cb wmi_rx_cb);
141 
142 /**
143  * qdf_reg_qmi_indication() - API to receive QMI Indication data
144  * @cb_ctx: QMI Indication recv callback context
145  * @qmi_ind_cb: QMI Indication event receive callback
146  *
147  * Return: QDF STATUS of operation
148  */
149 QDF_STATUS qdf_reg_qmi_indication(void *cb_ctx, qdf_qmi_ind_cb qmi_ind_cb);
150 
151 /**
152  * typedef qdf_is_driver_unloading_callback() - callback to get driver
153  *                                              unloading in progress or not
154  *
155  * Return: true if driver is unloading else false
156  */
157 typedef bool (*qdf_is_driver_unloading_callback)(void);
158 
159 /**
160  * qdf_register_is_driver_unloading_callback() - driver unloading callback
161  * @callback:  driver unloading callback
162  *
163  * Return: None
164  */
165 void qdf_register_is_driver_unloading_callback(
166 				qdf_is_driver_unloading_callback callback);
167 
168 /**
169  * typedef qdf_is_driver_state_module_stop_callback() - callback to get driver
170  *                                                 state is module stop or not
171  *
172  * Return: true if driver state is module stop else false
173  */
174 typedef bool (*qdf_is_driver_state_module_stop_callback)(void);
175 
176 /**
177  * qdf_register_is_driver_state_module_stop_callback() - driver state is
178  * module stop or not
179  * @callback:  driver state module stop callback
180  *
181  * Return: None
182  */
183 void qdf_register_is_driver_state_module_stop_callback(
184 			qdf_is_driver_state_module_stop_callback callback);
185 
186 /**
187  * qdf_register_self_recovery_callback() - register self recovery callback
188  * @callback:  self recovery callback
189  *
190  * Return: None
191  */
192 void qdf_register_self_recovery_callback(qdf_self_recovery_callback callback);
193 
194 /**
195  * qdf_trigger_self_recovery () - trigger self recovery
196  * @psoc: the psoc at which the recovery is being triggered
197  * @reason: the reason for the recovery request
198  *
199  * Call API only in case of fatal error,
200  * if self_recovery_cb callback is registered, injcets fw crash and recovers
201  * else raises QDF_BUG()
202  *
203  * Return: None
204  */
205 #define qdf_trigger_self_recovery(psoc, reason) \
206 	__qdf_trigger_self_recovery(psoc, reason, __func__, __LINE__)
207 void __qdf_trigger_self_recovery(void *psoc, enum qdf_hang_reason reason,
208 				 const char *func, const uint32_t line);
209 
210 /**
211  * typedef qdf_is_recovering_callback() - callback to get driver recovering in
212  * progress or not
213  *
214  * Return: true if driver is doing recovering else false
215  */
216 typedef bool (*qdf_is_recovering_callback)(void);
217 
218 /**
219  * qdf_register_recovering_state_query_callback() - register recover status
220  * query callback
221  * @is_recovering: true if driver is recovering
222  *
223  * Return: none
224  */
225 void qdf_register_recovering_state_query_callback(
226 	qdf_is_recovering_callback is_recovering);
227 
228 /**
229  * qdf_is_driver_unloading() - get driver unloading in progress status
230  * or not
231  *
232  * Return: true if driver is unloading else false
233  */
234 bool qdf_is_driver_unloading(void);
235 
236 /**
237  * qdf_is_driver_state_module_stop() - get driver state is module stop or not
238  *
239  * Return: true if driver state is module stop else false
240  */
241 bool qdf_is_driver_state_module_stop(void);
242 
243 /**
244  * qdf_is_recovering() - get driver recovering in progress status
245  * or not
246  *
247  * Return: true if driver is doing recovering else false
248  */
249 bool qdf_is_recovering(void);
250 
251 /*
252  * struct qdf_op_sync - opaque operation synchronization context handle
253  */
254 struct qdf_op_sync;
255 
256 typedef int (*qdf_op_protect_cb)(void **out_sync, const char *func);
257 typedef void (*qdf_op_unprotect_cb)(void *sync, const char *func);
258 
259 /**
260  * qdf_op_protect() - attempt to protect a driver operation
261  * @out_sync: output parameter for the synchronization context, populated on
262  *	success
263  *
264  * Return: Errno
265  */
266 #define qdf_op_protect(out_sync) __qdf_op_protect(out_sync, __func__)
267 
268 qdf_must_check int
269 __qdf_op_protect(struct qdf_op_sync **out_sync, const char *func);
270 
271 /**
272  * qdf_op_unprotect() - release driver operation protection
273  * @sync: synchronization context returned from qdf_op_protect()
274  *
275  * Return: None
276  */
277 #define qdf_op_unprotect(sync) __qdf_op_unprotect(sync, __func__)
278 
279 void __qdf_op_unprotect(struct qdf_op_sync *sync, const char *func);
280 
281 /**
282  * qdf_op_callbacks_register() - register driver operation protection callbacks
283  * @on_protect: callback on protect
284  * @on_unprotect: callback on unprotect
285  *
286  * Return: None
287  */
288 void qdf_op_callbacks_register(qdf_op_protect_cb on_protect,
289 			       qdf_op_unprotect_cb on_unprotect);
290 
291 /**
292  * typedef qdf_is_drv_connected_callback() - callback to query if drv
293  *                                           is connected
294  *
295  * Return: true if drv is connected else false
296  */
297 typedef bool (*qdf_is_drv_connected_callback)(void);
298 
299 /**
300  * qdf_is_drv_connected() - API to check if drv is connected or not
301  *
302  * DRV is dynamic request voting using which fw can do page fault and
303  * bring in page back without apps wake up
304  *
305  * Return: true: if drv is connected
306  *	   false: if drv is not connected
307  */
308 bool qdf_is_drv_connected(void);
309 
310 /**
311  * qdf_register_drv_connected_callback() - API to register drv connected cb
312  * @is_drv_connected: callback to query if drv is connected or not
313  *
314  * Return: none
315  */
316 void qdf_register_drv_connected_callback(qdf_is_drv_connected_callback
317 					 is_drv_connected);
318 
319 /**
320  * qdf_check_state_before_panic() - API to check if FW is down
321  * or driver is in recovery before calling assert
322  * @func: Caller function pointer used for debug info
323  * @line: Caller function line number
324  *
325  * Return: none
326  */
327 void qdf_check_state_before_panic(const char *func, const uint32_t line);
328 
329 /**
330  *typedef qdf_is_drv_supported_callback() - callback to query if drv is supported
331  *
332  * Return: true if drv is supported else false
333  */
334 typedef bool (*qdf_is_drv_supported_callback)(void);
335 
336 /**
337  * qdf_is_drv_supported() - API to check if drv is supported or not
338  *
339  * DRV is dynamic request voting using which fw can do page fault and
340  * bring in page back without apps wake up
341  *
342  * Return: true: if drv is supported
343  *	   false: if drv is not supported
344  */
345 bool qdf_is_drv_supported(void);
346 
347 /**
348  * qdf_register_drv_supported_callback() - API to register drv supported cb
349  * @is_drv_supported: callback to query if drv is supported or not
350  *
351  * Return: none
352  */
353 void qdf_register_drv_supported_callback(qdf_is_drv_supported_callback
354 					 is_drv_supported);
355 
356 /**
357  * typedef qdf_recovery_reason_update_callback() - recovery reason update callback
358  * @reason: recovery reason
359  */
360 typedef void (*qdf_recovery_reason_update_callback)(enum qdf_hang_reason
361 						    reason);
362 
363 /**
364  * qdf_register_recovery_reason_update() - Register callback to update recovery
365  *                                         reason
366  * @callback: callback to update recovery reason
367  *
368  * Return: none
369  */
370 void qdf_register_recovery_reason_update(qdf_recovery_reason_update_callback
371 					 callback);
372 
373 /**
374  * qdf_recovery_reason_update() - update recovery reason
375  * @reason: recovery reason
376  *
377  * Return: none
378  */
379 void qdf_recovery_reason_update(enum qdf_hang_reason reason);
380 
381 /**
382  * typedef qdf_bus_reg_dump() - callback for getting bus specific register dump
383  * @dev: Bus specific device
384  * @buf: Hang event buffer in which the data will be populated
385  * @len: length of data to be populated in the hang event buffer
386  *
387  * Return: none
388  */
389 typedef void (*qdf_bus_reg_dump)(struct device *dev, uint8_t *buf,
390 				 uint32_t len);
391 
392 /**
393  * qdf_register_get_bus_reg_dump() - Register callback to update bus register
394  *                                   dump
395  * @callback: callback to update bus register dump
396  *
397  * Return: none
398  */
399 void qdf_register_get_bus_reg_dump(qdf_bus_reg_dump callback);
400 
401 /**
402  * qdf_get_bus_reg_dump() - Get the register dump for the bus
403  * @dev: device
404  * @buf: buffer for hang data
405  * @len: len of hang data
406  *
407  * Return: none
408  */
409 void qdf_get_bus_reg_dump(struct device *dev, uint8_t *buf, uint32_t len);
410 
411 #ifdef WLAN_SUPPORT_DPDK
412 /**
413  * qdf_uio_register_device() - register dev to UIO dev
414  * @parent: parent device to be registered with UIO dev
415  * @info: UIO device capabilities
416  *
417  * Return: zero on success or a negative error code
418  */
419 int qdf_uio_register_device(struct device *parent, qdf_uio_info_t *info);
420 
421 /**
422  * qdf_uio_unregister_device - unregister a UIO device
423  * @info: UIO device capabilities
424  *
425  * Return: none
426  */
427 void qdf_uio_unregister_device(qdf_uio_info_t *info);
428 #endif
429 #endif /*_QDF_PLATFORM_H*/
430