1 /*
2 * Copyright (c) 2013-2014, 2016-2021 The Linux Foundation. All rights reserved.
3 * Copyright (c) 2022-2023 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 #ifndef _HTC_API_H_
21 #define _HTC_API_H_
22
23 #include <htc.h>
24 #include <htc_services.h>
25 #include <qdf_types.h> /* qdf_device_t */
26 #include "htc_packet.h"
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif /* __cplusplus */
31
32 /* TODO.. for BMI */
33 #define ENDPOINT1 0
34 /* TODO -remove me, but we have to fix BMI first */
35 #define HTC_MAILBOX_NUM_MAX 4
36
37 /* this is the amount of header room required by users of HTC */
38 #define HTC_HEADER_LEN HTC_HDR_LENGTH
39
40 #define HTC_HTT_TRANSFER_HDRSIZE 24
41
42 /*
43 * NOTE WELL: struct opaque_htc_handle is not defined anywhere. This
44 * reference is used to help ensure that a HTC_HANDLE is never used
45 * where a different handle type is expected
46 */
47 struct opaque_htc_handle;
48 typedef struct opaque_htc_handle *HTC_HANDLE;
49
50 typedef uint16_t HTC_SERVICE_ID;
51
52 typedef void (*HTC_TARGET_FAILURE)(void *Instance, QDF_STATUS Status);
53
54 struct htc_init_info {
55 void *pContext; /* context for target notifications */
56 void (*TargetFailure)(void *Instance, QDF_STATUS Status);
57 void (*TargetSendSuspendComplete)(void *ctx, bool is_nack,
58 uint16_t reason_code);
59 void (*target_initial_wakeup_cb)(void *cb_ctx);
60 void *target_psoc;
61 uint32_t cfg_wmi_credit_cnt;
62 /* HTC Pipe Ready Timeout in msecs */
63 uint32_t htc_ready_timeout_ms;
64 };
65
66 /* Struct for HTC layer packet stats*/
67 struct ol_ath_htc_stats {
68 int htc_get_pkt_q_fail_count;
69 int htc_pkt_q_empty_count;
70 int htc_send_q_empty_count;
71 };
72
73 /* To resume HTT Tx queue during runtime resume */
74 typedef void (*HTC_EP_RESUME_TX_QUEUE)(void *);
75
76 typedef int (*HTC_EP_PADDING_CREDIT_UPDATE) (void *, int);
77
78 /* per service connection send completion */
79 typedef void (*HTC_EP_SEND_PKT_COMPLETE)(void *, HTC_PACKET *);
80 /* per service connection callback when a plurality of packets have been sent
81 * The HTC_PACKET_QUEUE is a temporary queue object (e.g. freed on return from
82 * the callback) to hold a list of completed send packets.
83 * If the handler cannot fully traverse the packet queue before returning, it
84 * should transfer the items of the queue into the caller's private queue using:
85 * HTC_PACKET_ENQUEUE()
86 */
87 typedef void (*HTC_EP_SEND_PKT_COMP_MULTIPLE)(void *,
88 HTC_PACKET_QUEUE *);
89 /* per service connection pkt received */
90 typedef void (*HTC_EP_RECV_PKT)(void *, HTC_PACKET *);
91 /* per service connection callback when a plurality of packets are received
92 * The HTC_PACKET_QUEUE is a temporary queue object (e.g. freed on return from
93 * the callback) to hold a list of recv packets.
94 * If the handler cannot fully traverse the packet queue before returning, it
95 * should transfer the items of the queue into the caller's private queue using:
96 * HTC_PACKET_ENQUEUE()
97 */
98 typedef void (*HTC_EP_RECV_PKT_MULTIPLE)(void *, HTC_PACKET_QUEUE *);
99
100 /* Optional per service connection receive buffer re-fill callback,
101 * On some OSes (like Linux) packets are allocated from a global pool and
102 * indicated up to the network stack. The driver never gets the packets back
103 * from the OS. For these OSes a refill callback can be used to allocate and
104 * re-queue buffers into HTC.
105 *
106 * On other OSes, the network stack can call into the driver's OS-specific
107 * "return_packet" handler and the driver can re-queue these buffers into HTC.
108 * In this regard a refill callback is unnecessary
109 */
110 typedef void (*HTC_EP_RECV_REFILL)(void *, HTC_ENDPOINT_ID Endpoint);
111
112 /* Optional per service connection receive buffer allocation callback.
113 * On some systems packet buffers are an extremely limited resource. Rather than
114 * queue largest-possible-sized buffers to HTC, some systems would rather
115 * allocate a specific size as the packet is received. The trade off is
116 * slightly more processing (callback invoked for each RX packet)
117 * for the benefit of committing fewer buffer resources into HTC.
118 *
119 * The callback is provided the length of the pending packet to fetch. This
120 * includes the HTC header length plus the length of payload. The callback can
121 * return a pointer to the allocated HTC packet for immediate use.
122 *
123 * Alternatively a variant of this handler can be used to allocate large receive
124 * packets as needed. For example an application can use the refill mechanism
125 * for normal packets and the recv-alloc mechanism to handle the case where a
126 * large packet buffer is required. This can significantly reduce the
127 * amount of "committed" memory used to receive packets.
128 */
129 typedef HTC_PACKET *(*HTC_EP_RECV_ALLOC)(void *,
130 HTC_ENDPOINT_ID Endpoint,
131 int Length);
132
133 /* Optional per service connection callback to log packet information.
134 */
135 typedef void (*HTC_EP_LOG_PKT)(void *, HTC_PACKET *);
136
137 enum htc_send_full_action {
138 /* packet that overflowed should be kept in the queue */
139 HTC_SEND_FULL_KEEP = 0,
140 /* packet that overflowed should be dropped */
141 HTC_SEND_FULL_DROP = 1,
142 };
143
144 /* Optional per service connection callback when a send queue is full. This can
145 * occur if host continues queueing up TX packets faster than credits can arrive
146 * To prevent the host (on some Oses like Linux) from continuously queueing pkts
147 * and consuming resources, this callback is provided so that that the host
148 * can disable TX in the subsystem (i.e. network stack).
149 * This callback is invoked for each packet that "overflows" the HTC queue. The
150 * callback can determine whether the new packet that overflowed the queue can
151 * be kept (HTC_SEND_FULL_KEEP) or dropped (HTC_SEND_FULL_DROP). If a packet is
152 * dropped, the EpTxComplete handler will be called and the packet's status
153 * field will be set to A_NO_RESOURCE.
154 * Other OSes require a "per-packet" indication for each completed TX packet,
155 * this closed loop mechanism will prevent the network stack from overunning the
156 * NIC. The packet to keep or drop is passed for inspection to the registered
157 * handler the handler must ONLY inspect the packet, it may not free or reclaim
158 * the packet.
159 */
160 typedef enum htc_send_full_action (*HTC_EP_SEND_QUEUE_FULL)(void *,
161 HTC_PACKET *pPacket);
162
163 struct htc_ep_callbacks {
164 /* context for each callback */
165 void *pContext;
166 /* tx completion callback for connected endpoint */
167 HTC_EP_SEND_PKT_COMPLETE EpTxComplete;
168 /* receive callback for connected endpoint */
169 HTC_EP_RECV_PKT EpRecv;
170 /* OPTIONAL receive re-fill callback for connected endpoint */
171 HTC_EP_RECV_REFILL EpRecvRefill;
172 /* OPTIONAL send full callback */
173 HTC_EP_SEND_QUEUE_FULL EpSendFull;
174 /* OPTIONAL recv allocation callback */
175 HTC_EP_RECV_ALLOC EpRecvAlloc;
176 /* OPTIONAL recv allocation callback based on a threshold */
177 HTC_EP_RECV_ALLOC EpRecvAllocThresh;
178 /* OPTIONAL completion handler for multiple complete
179 * indications (EpTxComplete must be NULL)
180 */
181 HTC_EP_SEND_PKT_COMP_MULTIPLE EpTxCompleteMultiple;
182
183 HTC_EP_RESUME_TX_QUEUE ep_resume_tx_queue;
184
185 HTC_EP_PADDING_CREDIT_UPDATE ep_padding_credit_update;
186 /* if EpRecvAllocThresh is non-NULL, HTC will compare the
187 * threshold value to the current recv packet length and invoke
188 * the EpRecvAllocThresh callback to acquire a packet buffer
189 */
190 int RecvAllocThreshold;
191 /* if a EpRecvRefill handler is provided, this value
192 * can be used to set a trigger refill callback
193 * when the recv queue drops below this value
194 * if set to 0, the refill is only called when packets
195 * are empty
196 */
197 int RecvRefillWaterMark;
198 /* OPTIONAL callback to log packet information */
199 HTC_EP_LOG_PKT ep_log_pkt;
200 };
201
202 /* service connection information */
203 struct htc_service_connect_req {
204 /* service ID to connect to */
205 HTC_SERVICE_ID service_id;
206 /* connection flags, see htc protocol definition */
207 uint16_t ConnectionFlags;
208 /* ptr to optional service-specific meta-data */
209 uint8_t *pMetaData;
210 /* optional meta data length */
211 uint8_t MetaDataLength;
212 /* endpoint callbacks */
213 struct htc_ep_callbacks EpCallbacks;
214 /* maximum depth of any send queue */
215 int MaxSendQueueDepth;
216 /* HTC flags for the host-side (local) connection */
217 uint32_t LocalConnectionFlags;
218 /* override max message size in send direction */
219 unsigned int MaxSendMsgSize;
220 };
221
222 /* enable send bundle padding for this endpoint */
223 #define HTC_LOCAL_CONN_FLAGS_ENABLE_SEND_BUNDLE_PADDING (1 << 0)
224
225 /* service connection response information */
226 struct htc_service_connect_resp {
227 /* caller supplied buffer to optional meta-data */
228 uint8_t *pMetaData;
229 /* length of caller supplied buffer */
230 uint8_t BufferLength;
231 /* actual length of meta data */
232 uint8_t ActualLength;
233 /* endpoint to communicate over */
234 HTC_ENDPOINT_ID Endpoint;
235 /* max length of all messages over this endpoint */
236 unsigned int MaxMsgLength;
237 /* connect response code from target */
238 uint8_t ConnectRespCode;
239 };
240
241 /* endpoint distribution structure */
242 struct htc_endpoint_credit_dist {
243 struct _htc_endpoint_credit_dist *pNext;
244 struct _htc_endpoint_credit_dist *pPrev;
245 /* Service ID (set by HTC) */
246 HTC_SERVICE_ID service_id;
247 /* endpoint for this distribution struct (set by HTC) */
248 HTC_ENDPOINT_ID Endpoint;
249 /* distribution flags, distribution function can
250 * set default activity using SET_EP_ACTIVE() macro
251 */
252 uint32_t DistFlags;
253 /* credits for normal operation, anything above this
254 * indicates the endpoint is over-subscribed, this field
255 * is only relevant to the credit distribution function
256 */
257 int TxCreditsNorm;
258 /* floor for credit distribution, this field is
259 * only relevant to the credit distribution function
260 */
261 int TxCreditsMin;
262 /* number of credits assigned to this EP, this field
263 * is only relevant to the credit dist function
264 */
265 int TxCreditsAssigned;
266 /* current credits available, this field is used by
267 * HTC to determine whether a message can be sent or
268 * must be queued
269 */
270 int TxCredits;
271 /* pending credits to distribute on this endpoint, this
272 * is set by HTC when credit reports arrive.
273 * The credit distribution functions sets this to zero
274 * when it distributes the credits
275 */
276 int TxCreditsToDist;
277 /* this is the number of credits that the current pending TX
278 * packet needs to transmit. This is set by HTC when
279 * and endpoint needs credits in order to transmit
280 */
281 int TxCreditsSeek;
282 /* size in bytes of each credit (set by HTC) */
283 int TxCreditSize;
284 /* credits required for a maximum sized messages (set by HTC) */
285 int TxCreditsPerMaxMsg;
286 /* reserved for HTC use */
287 void *pHTCReserved;
288 /* current depth of TX queue , i.e. messages waiting for credits
289 * This field is valid only when HTC_CREDIT_DIST_ACTIVITY_CHANGE
290 * or HTC_CREDIT_DIST_SEND_COMPLETE is indicated on an endpoint
291 * that has non-zero credits to recover
292 */
293 int TxQueueDepth;
294 };
295
296 #define HTC_EP_ACTIVE ((uint32_t) (1u << 31))
297
298 /* macro to check if an endpoint has gone active, useful for credit
299 * distributions */
300 #define IS_EP_ACTIVE(epDist) ((epDist)->DistFlags & HTC_EP_ACTIVE)
301 #define SET_EP_ACTIVE(epDist) (epDist)->DistFlags |= HTC_EP_ACTIVE
302
303 /* credit distribution code that is passed into the distribution function,
304 * there are mandatory and optional codes that must be handled
305 */
306 enum htc_credit_dist_reason {
307 /* credits available as a result of completed
308 * send operations (MANDATORY) resulting in credit reports
309 */
310 HTC_CREDIT_DIST_SEND_COMPLETE = 0,
311 /* a change in endpoint activity occurred (OPTIONAL) */
312 HTC_CREDIT_DIST_ACTIVITY_CHANGE = 1,
313 /* an endpoint needs to "seek" credits (OPTIONAL) */
314 HTC_CREDIT_DIST_SEEK_CREDITS,
315 /* for debugging, dump any state information that is kept by
316 * the distribution function
317 */
318 HTC_DUMP_CREDIT_STATE
319 };
320
321 typedef void (*HTC_CREDIT_DIST_CALLBACK)(void *Context,
322 struct htc_endpoint_credit_dist *
323 pEPList,
324 enum htc_credit_dist_reason
325 Reason);
326
327 typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context,
328 struct htc_endpoint_credit_dist *
329 pEPList, int TotalCredits);
330
331 /* endpoint statistics action */
332 enum htc_endpoint_stat_action {
333 /* only read statistics */
334 HTC_EP_STAT_SAMPLE = 0,
335 /* sample and immediately clear statistics */
336 HTC_EP_STAT_SAMPLE_AND_CLEAR = 1,
337 /* clear only */
338 HTC_EP_STAT_CLEAR
339 };
340
341 /* endpoint statistics */
342 struct htc_endpoint_stats {
343 /* number of TX packets posted to the endpoint */
344 uint32_t TxPosted;
345 /* number of times the host set the credit-low flag in a send message on
346 * this endpoint
347 */
348 uint32_t TxCreditLowIndications;
349 /* running count of total TX packets issued */
350 uint32_t TxIssued;
351 /* running count of TX packets that were issued in bundles */
352 uint32_t TxPacketsBundled;
353 /* running count of TX bundles that were issued */
354 uint32_t TxBundles;
355 /* tx packets that were dropped */
356 uint32_t TxDropped;
357 /* running count of total credit reports received for this endpoint */
358 uint32_t TxCreditRpts;
359 /* credit reports received from this endpoint's RX packets */
360 uint32_t TxCreditRptsFromRx;
361 /* credit reports received from RX packets of other endpoints */
362 uint32_t TxCreditRptsFromOther;
363 /* credit reports received from endpoint 0 RX packets */
364 uint32_t TxCreditRptsFromEp0;
365 /* count of credits received via Rx packets on this endpoint */
366 uint32_t TxCreditsFromRx;
367 /* count of credits received via another endpoint */
368 uint32_t TxCreditsFromOther;
369 /* count of credits received via another endpoint */
370 uint32_t TxCreditsFromEp0;
371 /* count of consumed credits */
372 uint32_t TxCreditsConsummed;
373 /* count of credits returned */
374 uint32_t TxCreditsReturned;
375 /* count of RX packets received */
376 uint32_t RxReceived;
377 /* count of lookahead records
378 * found in messages received on this endpoint
379 */
380 uint32_t RxLookAheads;
381 /* count of recv packets received in a bundle */
382 uint32_t RxPacketsBundled;
383 /* count of number of bundled lookaheads */
384 uint32_t RxBundleLookAheads;
385 /* count of the number of bundle indications from the HTC header */
386 uint32_t RxBundleIndFromHdr;
387 /* number of times the recv allocation threshold was hit */
388 uint32_t RxAllocThreshHit;
389 /* total number of bytes */
390 uint32_t RxAllocThreshBytes;
391 };
392
393 /**
394 * enum htc_link_vote_user_id - user ids for each link vote type
395 * @HTC_LINK_VOTE_INVALID_MIN_USER_ID: min user id
396 * @HTC_LINK_VOTE_SAP_USER_ID: sap user id
397 * @HTC_LINK_VOTE_GO_USER_ID: go user id
398 * @HTC_LINK_VOTE_NDP_USER_ID: ndp user id
399 * @HTC_LINK_VOTE_SAP_DFS_USER_ID: sap dfs user id
400 * @HTC_LINK_VOTE_STA_USER_ID: sta user id
401 * @HTC_LINK_VOTE_DIRECT_LINK_USER_ID: Direct link user ID
402 * @HTC_LINK_VOTE_INVALID_MAX_USER_ID: max user id
403 */
404 enum htc_link_vote_user_id {
405 HTC_LINK_VOTE_INVALID_MIN_USER_ID = 0,
406 HTC_LINK_VOTE_SAP_USER_ID = 1,
407 HTC_LINK_VOTE_GO_USER_ID = 2,
408 HTC_LINK_VOTE_NDP_USER_ID = 3,
409 HTC_LINK_VOTE_SAP_DFS_USER_ID = 4,
410 HTC_LINK_VOTE_STA_USER_ID = 5,
411 HTC_LINK_VOTE_DIRECT_LINK_USER_ID = 6,
412 HTC_LINK_VOTE_INVALID_MAX_USER_ID
413 };
414
415 /* ------ Function Prototypes ------ */
416 /**
417 * htc_create() - Create an instance of HTC over the underlying HIF device
418 * @HifDevice: hif device handle,
419 * @pInfo: initialization information
420 * @osdev: QDF device structure
421 * @con_mode: driver connection mode
422 *
423 * Return: HTC_HANDLE on success, NULL on failure
424 */
425 HTC_HANDLE htc_create(void *HifDevice, struct htc_init_info *pInfo,
426 qdf_device_t osdev, uint32_t con_mode);
427
428 /**
429 * htc_get_hif_device() - Get the underlying HIF device handle
430 * @HTCHandle: handle passed into the AddInstance callback
431 *
432 * Return: opaque HIF device handle usable in HIF API calls.
433 */
434 void *htc_get_hif_device(HTC_HANDLE HTCHandle);
435
436 /**
437 * htc_set_credit_distribution() - Set credit distribution parameters
438 * @HTCHandle: HTC handle
439 * @pCreditDistContext: caller supplied context to pass into distribution
440 * functions
441 * @CreditDistFunc: Distribution function callback
442 * @CreditInitFunc: Credit Distribution initialization callback
443 * @ServicePriorityOrder: Array containing list of service IDs, lowest index
444 * is highestpriority
445 * @ListLength: number of elements in ServicePriorityOrder
446 *
447 * The user can set a custom credit distribution function to handle
448 * special requirementsfor each endpoint. A default credit distribution
449 * routine can be used by setting CreditInitFunc to NULL. The default
450 * credit distribution is only provided for simple "fair" credit distribution
451 * without regard to any prioritization.
452 *
453 * Return: None
454 */
455 void htc_set_credit_distribution(HTC_HANDLE HTCHandle,
456 void *pCreditDistContext,
457 HTC_CREDIT_DIST_CALLBACK CreditDistFunc,
458 HTC_CREDIT_INIT_CALLBACK CreditInitFunc,
459 HTC_SERVICE_ID ServicePriorityOrder[],
460 int ListLength);
461
462 /**
463 * htc_wait_target() - Wait for the target to indicate the HTC layer is ready
464 * @HTCHandle: HTC handle
465 *
466 * This API blocks until the target responds with an HTC ready message.
467 * The caller should not connect services until the target has indicated it is
468 * ready.
469 *
470 * Return: None
471 */
472 QDF_STATUS htc_wait_target(HTC_HANDLE HTCHandle);
473
474 /**
475 * htc_start() - Start target service communications
476 * @HTCHandle: HTC handle
477 *
478 * This API indicates to the target that the service connection phase
479 * is completeand the target can freely start all connected services. This
480 * API should only be called AFTER all service connections have been made.
481 * TCStart will issue a SETUP_COMPLETE message to the target to indicate that
482 * all service connections have been made and the target can start
483 * communicating over the endpoints.
484 * Return: None
485 */
486 QDF_STATUS htc_start(HTC_HANDLE HTCHandle);
487
488 /**
489 * htc_connect_service() - Connect to an HTC service
490 * @HTCHandle: HTC handle
491 * @pReq: connection details
492 * @pResp: connection response
493 *
494 * Service connections must be performed before htc_start.
495 * User provides callback handlersfor various endpoint events.
496 * Return: None
497 */
498 QDF_STATUS htc_connect_service(HTC_HANDLE HTCHandle,
499 struct htc_service_connect_req *pReq,
500 struct htc_service_connect_resp *pResp);
501
502 /**
503 * htc_dump() - HTC register log dump
504 * @HTCHandle: HTC handle
505 * @CmdId: Log command
506 * @start: start/print logs
507 *
508 * Register logs will be started/printed/ be flushed.
509 *
510 * Return: None
511 */
512 void htc_dump(HTC_HANDLE HTCHandle, uint8_t CmdId, bool start);
513
514 /**
515 * htc_ce_tasklet_debug_dump() - Dump ce tasklet rings debug data
516 * @htc_handle: HTC handle
517 *
518 * Debug logs will be printed.
519 *
520 * Return: None
521 */
522 void htc_ce_tasklet_debug_dump(HTC_HANDLE htc_handle);
523
524 /**
525 * htc_send_pkt() - Send an HTC packet
526 * @HTCHandle: HTC handle
527 * @pPacket: packet to send
528 *
529 * Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro.
530 * This interface is fully asynchronous. On error, HTC SendPkt will
531 * call the registered Endpoint callback to cleanup the packet.
532 *
533 * Return: QDF_STATUS_SUCCESS
534 */
535 QDF_STATUS htc_send_pkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
536
537 #ifdef CUSTOM_CB_SCHEDULER_SUPPORT
538 /**
539 * htc_register_custom_cb() - Helper API to register the custom callback
540 * @htc_handle: HTC handle
541 * @endpoint_id: Endpoint ID
542 * @custom_cb: Custom call back function pointer
543 * @custom_cb_context: Custom callback context
544 *
545 * return: QDF_STATUS
546 */
547 QDF_STATUS
548 htc_register_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id,
549 void (*custom_cb)(void *), void *custom_cb_context);
550
551 /**
552 * htc_unregister_custom_cb() - Helper API to unregister the custom callback
553 * @htc_handle: HTC handle
554 * @endpoint_id: Endpoint ID
555 *
556 * return: QDF_STATUS
557 */
558 QDF_STATUS
559 htc_unregister_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id);
560
561 /**
562 * htc_enable_custom_cb() - Helper API to enable the custom callback
563 * @htc_handle: HTC handle
564 * @endpoint_id: Endpoint ID
565 *
566 * return: QDF_STATUS
567 */
568 QDF_STATUS
569 htc_enable_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id);
570
571 /**
572 * htc_disable_custom_cb() - Helper API to disable the custom callback
573 * @htc_handle: HTC handle
574 * @endpoint_id: Endpoint ID
575 *
576 * return: QDF_STATUS
577 */
578 QDF_STATUS
579 htc_disable_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id);
580 #else
581 /**
582 * htc_register_custom_cb() - Helper API to register the custom callback
583 * @htc_handle: HTC handle
584 * @endpoint_id: Endpoint ID
585 * @custom_cb: Custom call back function pointer
586 * @custom_cb_context: Custom callback context
587 *
588 * return: QDF_STATUS
589 */
590 static inline QDF_STATUS
htc_register_custom_cb(HTC_HANDLE htc_handle,HTC_ENDPOINT_ID endpoint_id,void (* custom_cb)(void *),void * custom_cb_context)591 htc_register_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id,
592 void (*custom_cb)(void *), void *custom_cb_context)
593 {
594 return QDF_STATUS_SUCCESS;
595 }
596
597 /**
598 * htc_unregister_custom_cb() - Helper API to unregister the custom callback
599 * @htc_handle: HTC handle
600 * @endpoint_id: Endpoint ID
601 *
602 * return: QDF_STATUS
603 */
604 static inline QDF_STATUS
htc_unregister_custom_cb(HTC_HANDLE htc_handle,HTC_ENDPOINT_ID endpoint_id)605 htc_unregister_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id)
606 {
607 return QDF_STATUS_SUCCESS;
608 }
609
610 /**
611 * htc_enable_custom_cb() - Helper API to enable the custom callback
612 * @htc_handle: HTC handle
613 * @endpoint_id: Endpoint ID
614 *
615 * return: QDF_STATUS
616 */
617 static inline QDF_STATUS
htc_enable_custom_cb(HTC_HANDLE htc_handle,HTC_ENDPOINT_ID endpoint_id)618 htc_enable_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id)
619 {
620 return QDF_STATUS_SUCCESS;
621 }
622
623 /**
624 * htc_disable_custom_cb() - Helper API to disable the custom callback
625 * @htc_handle: HTC handle
626 * @endpoint_id: Endpoint ID
627 *
628 * return: QDF_STATUS
629 */
630 static inline QDF_STATUS
htc_disable_custom_cb(HTC_HANDLE htc_handle,HTC_ENDPOINT_ID endpoint_id)631 htc_disable_custom_cb(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id)
632 {
633 return QDF_STATUS_SUCCESS;
634 }
635 #endif /* CUSTOM_CB_SCHEDULER_SUPPORT */
636
637 #ifdef ATH_11AC_TXCOMPACT
638 /**
639 * htc_send_data_pkt() - Send an HTC packet containing a tx descriptor and data
640 * @HTCHandle: HTC handle
641 * @netbuf: network buffer containing the packet to send
642 * @Epid: endpoint id
643 * @ActualLength: actual length of the packet
644 *
645 * Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro.
646 * Caller must provide headroom in an initial fragment added to the
647 * network buffer to store a HTC_FRAME_HDR.
648 * This interface is fully asynchronous. On error, htc_send_data_pkt will
649 * call the registered Endpoint EpDataTxComplete callback to cleanup
650 * the packet.
651 *
652 * Return: QDF_STATUS
653 */
654 QDF_STATUS htc_send_data_pkt(HTC_HANDLE HTCHandle, qdf_nbuf_t netbuf,
655 int Epid, int ActualLength);
656 #else /*ATH_11AC_TXCOMPACT */
657 /**
658 * htc_send_data_pkt() - Send an HTC packet containing a tx descriptor and data
659 * @HTCHandle: HTC handle
660 * @pPacket: packet to send
661 * @more_data:
662 *
663 * Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro.
664 * Caller must provide headroom in an initial fragment added to the
665 * network buffer to store a HTC_FRAME_HDR.
666 * This interface is fully asynchronous. On error, htc_send_data_pkt will
667 * call the registered Endpoint EpDataTxComplete callback to cleanup
668 * the packet.
669 *
670 * Return: QDF_STATUS
671 */
672 QDF_STATUS htc_send_data_pkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket,
673 uint8_t more_data);
674 #endif /*ATH_11AC_TXCOMPACT */
675
676 /**
677 * htc_flush_surprise_remove() - Flush HTC when target is removed surprisely
678 * service communications
679 * @HTCHandle: HTC handle
680 *
681 * All receive and pending TX packets will be flushed.
682 * Return: None
683 */
684 void htc_flush_surprise_remove(HTC_HANDLE HTCHandle);
685
686 /**
687 * htc_stop() - Stop HTC service communications
688 * @HTCHandle: HTC handle
689 *
690 * HTC communications is halted. All receive and pending TX packets
691 * will be flushed.
692 * Return: None
693 */
694 void htc_stop(HTC_HANDLE HTCHandle);
695
696 /**
697 * htc_destroy() - Destroy HTC service
698 * @HTCHandle: HTC handle
699 *
700 * This cleans up all resources allocated by htc_create().
701 * Return: None
702 */
703 void htc_destroy(HTC_HANDLE HTCHandle);
704
705 /**
706 * htc_flush_endpoint() - Flush pending TX packets
707 * @HTCHandle: HTC handle
708 * @Endpoint: Endpoint to flush
709 * @Tag: flush tag
710 *
711 * The Tag parameter is used to selectively flush packets with matching
712 * tags. The value of 0 forces all packets to be flush regardless of tag
713 * Return: None
714 */
715 void htc_flush_endpoint(HTC_HANDLE HTCHandle, HTC_ENDPOINT_ID Endpoint,
716 HTC_TX_TAG Tag);
717 /**
718 * htc_dump_credit_states() - Dump credit distribution state
719 * @HTCHandle: HTC handle
720 *
721 * This dumps all credit distribution information to the debugger
722 * Return: None
723 */
724 void htc_dump_credit_states(HTC_HANDLE HTCHandle);
725
726 /**
727 * htc_indicate_activity_change() - Indicate a traffic activity change on an
728 * endpoint
729 * @HTCHandle: HTC handle
730 * @Endpoint: endpoint in which activity has changed
731 * @Active: true if active, false if it has become inactive
732 *
733 * This triggers the registered credit distribution function to
734 * re-adjust credits for active/inactive endpoints.
735 * Return: None
736 */
737 void htc_indicate_activity_change(HTC_HANDLE HTCHandle,
738 HTC_ENDPOINT_ID Endpoint, bool Active);
739
740 /**
741 * htc_get_endpoint_statistics() - Get endpoint statistics
742 * @HTCHandle: HTC handle
743 * @Endpoint: Endpoint identifier
744 * @Action: action to take with statistics
745 * @pStats: statistics that were sampled (can be NULL if Action is
746 * HTC_EP_STAT_CLEAR)
747 *
748 * Statistics is a compile-time option and this function may return
749 * false if HTC is not compiled with profiling.
750 * The caller can specify the statistic "action" to take when sampling
751 * the statistics. This includes :
752 * HTC_EP_STAT_SAMPLE : The pStats structure is filled with the current
753 * values.
754 * HTC_EP_STAT_SAMPLE_AND_CLEAR : The structure is filled and the current
755 * statisticsare cleared.
756 * HTC_EP_STAT_CLEA : the statistics are cleared, the called can pass
757 * a NULL value for pStats
758 * Return: true if statistics profiling is enabled, otherwise false.
759 */
760 bool htc_get_endpoint_statistics(HTC_HANDLE HTCHandle,
761 HTC_ENDPOINT_ID Endpoint,
762 enum htc_endpoint_stat_action Action,
763 struct htc_endpoint_stats *pStats);
764
765 /**
766 * htc_unblock_recv() - Unblock HTC message reception
767 * @HTCHandle: HTC handle
768 *
769 * HTC will block the receiver if the EpRecvAlloc callback fails to provide a
770 * packet. The caller can use this API to indicate to HTC when resources
771 * (buffers) are available such that the receiver can be unblocked and HTC
772 * may re-attempt fetching the pending message.
773 * This API is not required if the user uses the EpRecvRefill callback or uses
774 * the HTCAddReceivePacket()API to recycle or provide receive packets to HTC.
775 * Return: None
776 */
777 void htc_unblock_recv(HTC_HANDLE HTCHandle);
778
779 /**
780 * htc_add_receive_pkt_multiple() - Add multiple receive packets to HTC
781 * @HTCHandle: HTC handle
782 * @pPktQueue: HTC receive packet queue holding packets to add
783 *
784 * User must supply HTC packets for capturing incoming HTC frames.
785 * The caller mmust initialize each HTC packet using the
786 * SET_HTC_PACKET_INFO_RX_REFILL() macro. The queue must only contain
787 * recv packets for the same endpoint. Caller supplies a pointer to an
788 * HTC_PACKET_QUEUE structure holding the recv packet. This API will
789 * remove the packets from the pkt queue and place them into internal
790 * recv packet list.
791 * The caller may allocate the pkt queue on the stack to hold the pkts.
792 * Return: A_OK on success
793 */
794 A_STATUS htc_add_receive_pkt_multiple(HTC_HANDLE HTCHandle,
795 HTC_PACKET_QUEUE *pPktQueue);
796
797 /**
798 * htc_is_endpoint_active() - Check if an endpoint is marked active
799 * @HTCHandle: HTC handle
800 * @Endpoint: endpoint to check for active state
801 *
802 * Return: returns true if Endpoint is Active
803 */
804 bool htc_is_endpoint_active(HTC_HANDLE HTCHandle,
805 HTC_ENDPOINT_ID Endpoint);
806
807 /**
808 * htc_set_pkt_dbg() - Set up debug flag for HTC packets
809 * @handle: HTC handle
810 * @dbg_flag: enable or disable flag
811 *
812 * Return: none
813 */
814 void htc_set_pkt_dbg(HTC_HANDLE handle, A_BOOL dbg_flag);
815
816 /**
817 * htc_set_nodrop_pkt() - Set up nodrop pkt flag for mboxping nodrop pkt
818 * @HTCHandle: HTC handle
819 * @isNodropPkt: indicates whether it is nodrop pkt
820 *
821 * Return: None
822 *
823 */
824 void htc_set_nodrop_pkt(HTC_HANDLE HTCHandle, A_BOOL isNodropPkt);
825
826 /**
827 * htc_enable_hdr_length_check() - Set up htc_hdr_length_check flag
828 * @htc_handle: HTC handle
829 * @htc_hdr_length_check: flag to indicate whether htc header length check is
830 * required
831 *
832 * Return: None
833 *
834 */
835 void
836 htc_enable_hdr_length_check(HTC_HANDLE htc_handle, bool htc_hdr_length_check);
837
838 /**
839 * htc_get_num_recv_buffers() - Get the number of recv buffers currently queued
840 * into an HTC endpoint
841 * @HTCHandle: HTC handle
842 * @Endpoint: endpoint to check
843 *
844 * Return: returns number of buffers in queue
845 *
846 */
847 int htc_get_num_recv_buffers(HTC_HANDLE HTCHandle,
848 HTC_ENDPOINT_ID Endpoint);
849
850 /**
851 * htc_set_target_failure_callback() - Set the target failure handling callback
852 * in HTC layer
853 * @HTCHandle: HTC handle
854 * @Callback: target failure handling callback
855 *
856 * Return: None
857 */
858 void htc_set_target_failure_callback(HTC_HANDLE HTCHandle,
859 HTC_TARGET_FAILURE Callback);
860
861 /* internally used functions for testing... */
862 void htc_enable_recv(HTC_HANDLE HTCHandle);
863 void htc_disable_recv(HTC_HANDLE HTCHandle);
864 A_STATUS HTCWaitForPendingRecv(HTC_HANDLE HTCHandle,
865 uint32_t TimeoutInMs,
866 bool *pbIsRecvPending);
867
868 /* function to fetch stats from htc layer*/
869 struct ol_ath_htc_stats *ieee80211_ioctl_get_htc_stats(HTC_HANDLE
870 HTCHandle);
871 /**
872 * htc_get_tx_queue_depth() - get the tx queue depth of an htc endpoint
873 * @htc_handle: htc handle
874 * @endpoint_id: endpoint to check
875 *
876 * Return: htc_handle tx queue depth
877 */
878 int htc_get_tx_queue_depth(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id);
879
880 #ifdef WLAN_FEATURE_FASTPATH
881 void htc_ctrl_msg_cmpl(HTC_HANDLE htc_pdev, HTC_ENDPOINT_ID htc_ep_id);
882
883 #define HTC_TX_DESC_FILL(_htc_tx_desc, _download_len, _ep_id, _seq_no) \
884 do { \
885 HTC_WRITE32((_htc_tx_desc), \
886 SM((_download_len), HTC_FRAME_HDR_PAYLOADLEN) | \
887 SM((_ep_id), HTC_FRAME_HDR_ENDPOINTID)); \
888 HTC_WRITE32((uint32_t *)(_htc_tx_desc) + 1, \
889 SM((_seq_no), HTC_FRAME_HDR_CONTROLBYTES1)); \
890 } while (0)
891 #endif /* WLAN_FEATURE_FASTPATH */
892
893 #ifdef __cplusplus
894 }
895 #endif
896 void htc_get_control_endpoint_tx_host_credits(HTC_HANDLE HTCHandle,
897 int *credit);
898 void htc_dump_counter_info(HTC_HANDLE HTCHandle);
899 void *htc_get_targetdef(HTC_HANDLE htc_handle);
900 #ifdef FEATURE_RUNTIME_PM
901 int htc_runtime_suspend(HTC_HANDLE htc_ctx);
902 int htc_runtime_resume(HTC_HANDLE htc_ctx);
903 #endif
904 void htc_global_credit_flow_disable(void);
905 void htc_global_credit_flow_enable(void);
906
907 /* Disable ASPM : Disable PCIe low power */
908 bool htc_can_suspend_link(HTC_HANDLE HTCHandle);
909
910 #ifdef IPA_OFFLOAD
911 void htc_ipa_get_ce_resource(HTC_HANDLE htc_handle,
912 qdf_shared_mem_t **ce_sr,
913 uint32_t *ce_sr_ring_size,
914 qdf_dma_addr_t *ce_reg_paddr);
915 #else
916 #define htc_ipa_get_ce_resource(htc_handle, \
917 ce_sr, ce_sr_ring_size, ce_reg_paddr) /* NO-OP */
918 #endif /* IPA_OFFLOAD */
919
920 #if defined(DEBUG_HL_LOGGING) && defined(CONFIG_HL_SUPPORT)
921
922 /**
923 * htc_dump_bundle_stats() - dump tx and rx htc message bundle stats
924 * @HTCHandle: htc handle
925 *
926 * Return: None
927 */
928 void htc_dump_bundle_stats(HTC_HANDLE HTCHandle);
929
930 /**
931 * htc_clear_bundle_stats() - clear tx and rx htc message bundle stats
932 * @HTCHandle: htc handle
933 *
934 * Return: None
935 */
936 void htc_clear_bundle_stats(HTC_HANDLE HTCHandle);
937 #endif
938
939 #ifdef FEATURE_RUNTIME_PM
940 int htc_pm_runtime_get(HTC_HANDLE htc_handle);
941 int htc_pm_runtime_put(HTC_HANDLE htc_handle);
942
943 /**
944 * htc_dec_return_htt_runtime_cnt: Decrement htc htt runtime count
945 * @htc: HTC handle
946 *
947 * Return: value of runtime count after decrement
948 */
949 int32_t htc_dec_return_htt_runtime_cnt(HTC_HANDLE htc);
950 #else
htc_pm_runtime_get(HTC_HANDLE htc_handle)951 static inline int htc_pm_runtime_get(HTC_HANDLE htc_handle) { return 0; }
htc_pm_runtime_put(HTC_HANDLE htc_handle)952 static inline int htc_pm_runtime_put(HTC_HANDLE htc_handle) { return 0; }
953
954 static inline
htc_dec_return_htt_runtime_cnt(HTC_HANDLE htc)955 int32_t htc_dec_return_htt_runtime_cnt(HTC_HANDLE htc)
956 {
957 return -1;
958 }
959 #endif
960
961 #ifdef WLAN_DEBUG_LINK_VOTE
962 /**
963 * htc_log_link_user_votes() - API to log link user votes
964 *
965 * API to log the link user votes
966 *
967 * Return: void
968 */
969 void htc_log_link_user_votes(void);
970
971 /**
972 * htc_vote_link_down() - API to vote for link down
973 * @htc_handle: HTC handle
974 * @id: PCIe link vote user id
975 *
976 * API for upper layers to call HIF to vote for link down
977 *
978 * Return: void
979 */
980 void htc_vote_link_down(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id);
981
982 /**
983 * htc_vote_link_up() - API to vote for link up
984 * @htc_handle: HTC Handle
985 * @id: PCIe link vote user id
986 *
987 * API for upper layers to call HIF to vote for link up
988 *
989 * Return: void
990 */
991 void htc_vote_link_up(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id);
992
993 #else
994 static inline
htc_log_link_user_votes(void)995 void htc_log_link_user_votes(void)
996 {
997 }
998
999 static inline
htc_vote_link_down(HTC_HANDLE htc_handle,enum htc_link_vote_user_id id)1000 void htc_vote_link_down(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id)
1001 {
1002 }
1003
1004 static inline
htc_vote_link_up(HTC_HANDLE htc_handle,enum htc_link_vote_user_id id)1005 void htc_vote_link_up(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id)
1006 {
1007 }
1008 #endif
1009
1010 /**
1011 * htc_set_async_ep() - set async HTC end point
1012 * user should call this function after htc_connect_service before
1013 * queueing any packets to end point
1014 * @HTCHandle: htc handle
1015 * @htc_ep_id: end point id
1016 * @value: true or false
1017 *
1018 * Return: None
1019 */
1020 void htc_set_async_ep(HTC_HANDLE HTCHandle,
1021 HTC_ENDPOINT_ID htc_ep_id, bool value);
1022
1023 /**
1024 * htc_set_wmi_endpoint_count: Set number of WMI endpoint
1025 * @htc_handle: HTC handle
1026 * @wmi_ep_count: WMI endpoint count
1027 *
1028 * return: None
1029 */
1030 void htc_set_wmi_endpoint_count(HTC_HANDLE htc_handle, uint8_t wmi_ep_count);
1031
1032 /**
1033 * htc_get_wmi_endpoint_count: Get number of WMI endpoint
1034 * @htc_handle: HTC handle
1035 *
1036 * return: WMI endpoint count
1037 */
1038 uint8_t htc_get_wmi_endpoint_count(HTC_HANDLE htc_handle);
1039
1040 /**
1041 * htc_print_credit_history: print HTC credit history in buffer
1042 * @htc: HTC handle
1043 * @count: Number of lines to be copied
1044 * @print: Print callback to print in the buffer
1045 * @print_priv: any data required by the print method, e.g. a file handle
1046 *
1047 * return: None
1048 */
1049 #ifdef FEATURE_HTC_CREDIT_HISTORY
1050 void htc_print_credit_history(HTC_HANDLE htc, uint32_t count,
1051 qdf_abstract_print * print, void *print_priv);
1052 #else
1053 static inline
htc_print_credit_history(HTC_HANDLE htc,uint32_t count,qdf_abstract_print * print,void * print_priv)1054 void htc_print_credit_history(HTC_HANDLE htc, uint32_t count,
1055 qdf_abstract_print *print, void *print_priv)
1056 {
1057 print(print_priv, "HTC Credit History Feature is disabled");
1058 }
1059 #endif
1060
1061 #ifdef SYSTEM_PM_CHECK
1062 /**
1063 * htc_system_resume() - Send out any pending WMI/HTT
1064 * messages pending in htc queues on system resume.
1065 * @htc: HTC handle
1066 *
1067 * Return: None
1068 */
1069 void htc_system_resume(HTC_HANDLE htc);
1070 #else
htc_system_resume(HTC_HANDLE htc)1071 static inline void htc_system_resume(HTC_HANDLE htc)
1072 {
1073 }
1074 #endif
1075 #endif /* _HTC_API_H_ */
1076