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