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