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 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 * enum 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 * @pCreditDistContext: caller supplied context to pass into distribution 437 * functions 438 * @CreditDistFunc: Distribution function callback 439 * @CreditInitFunc: Credit Distribution initialization callback 440 * @ServicePriorityOrder: Array containing list of service IDs, lowest index 441 * is highestpriority 442 * @ListLength: number of elements in ServicePriorityOrder 443 * 444 * The user can set a custom credit distribution function to handle 445 * special requirementsfor each endpoint. A default credit distribution 446 * routine can be used by setting CreditInitFunc to NULL. The default 447 * credit distribution is only provided for simple "fair" credit distribution 448 * without regard to any prioritization. 449 * 450 * Return: None 451 */ 452 void htc_set_credit_distribution(HTC_HANDLE HTCHandle, 453 void *pCreditDistContext, 454 HTC_CREDIT_DIST_CALLBACK CreditDistFunc, 455 HTC_CREDIT_INIT_CALLBACK CreditInitFunc, 456 HTC_SERVICE_ID ServicePriorityOrder[], 457 int ListLength); 458 459 /** 460 * htc_wait_target() - Wait for the target to indicate the HTC layer is ready 461 * @HTCHandle: HTC handle 462 * 463 * This API blocks until the target responds with an HTC ready message. 464 * The caller should not connect services until the target has indicated it is 465 * ready. 466 * 467 * Return: None 468 */ 469 QDF_STATUS htc_wait_target(HTC_HANDLE HTCHandle); 470 471 /** 472 * htc_start() - Start target service communications 473 * @HTCHandle: HTC handle 474 * 475 * This API indicates to the target that the service connection phase 476 * is completeand the target can freely start all connected services. This 477 * API should only be called AFTER all service connections have been made. 478 * TCStart will issue a SETUP_COMPLETE message to the target to indicate that 479 * all service connections have been made and the target can start 480 * communicating over the endpoints. 481 * Return: None 482 */ 483 QDF_STATUS htc_start(HTC_HANDLE HTCHandle); 484 485 /** 486 * htc_connect_service() - Connect to an HTC service 487 * @HTCHandle: HTC handle 488 * @pReq: connection details 489 * @pResp: connection response 490 * 491 * Service connections must be performed before htc_start. 492 * User provides callback handlersfor various endpoint events. 493 * Return: None 494 */ 495 QDF_STATUS htc_connect_service(HTC_HANDLE HTCHandle, 496 struct htc_service_connect_req *pReq, 497 struct htc_service_connect_resp *pResp); 498 499 /** 500 * htc_dump() - HTC register log dump 501 * @HTCHandle: HTC handle 502 * @CmdId: Log command 503 * @start: start/print logs 504 * 505 * Register logs will be started/printed/ be flushed. 506 * 507 * Return: None 508 */ 509 void htc_dump(HTC_HANDLE HTCHandle, uint8_t CmdId, bool start); 510 511 /** 512 * htc_ce_tasklet_debug_dump() - Dump ce tasklet rings debug data 513 * @htc_handle: HTC handle 514 * 515 * Debug logs will be printed. 516 * 517 * Return: None 518 */ 519 void htc_ce_tasklet_debug_dump(HTC_HANDLE htc_handle); 520 521 /** 522 * htc_send_pkt() - Send an HTC packet 523 * @HTCHandle: HTC handle 524 * @pPacket: packet to send 525 * 526 * Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro. 527 * This interface is fully asynchronous. On error, HTC SendPkt will 528 * call the registered Endpoint callback to cleanup the packet. 529 * 530 * Return: QDF_STATUS_SUCCESS 531 */ 532 QDF_STATUS htc_send_pkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket); 533 534 #ifdef ATH_11AC_TXCOMPACT 535 /** 536 * htc_send_data_pkt() - Send an HTC packet containing a tx descriptor and data 537 * @HTCHandle: HTC handle 538 * @netbuf: network buffer containing the packet to send 539 * @Epid: endpoint id 540 * @ActualLength: actual length of the packet 541 * 542 * Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro. 543 * Caller must provide headroom in an initial fragment added to the 544 * network buffer to store a HTC_FRAME_HDR. 545 * This interface is fully asynchronous. On error, htc_send_data_pkt will 546 * call the registered Endpoint EpDataTxComplete callback to cleanup 547 * the packet. 548 * 549 * Return: QDF_STATUS 550 */ 551 QDF_STATUS htc_send_data_pkt(HTC_HANDLE HTCHandle, qdf_nbuf_t netbuf, 552 int Epid, int ActualLength); 553 #else /*ATH_11AC_TXCOMPACT */ 554 /** 555 * htc_send_data_pkt() - Send an HTC packet containing a tx descriptor and data 556 * @HTCHandle: HTC handle 557 * @pPacket: packet to send 558 * @more_data: 559 * 560 * Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro. 561 * Caller must provide headroom in an initial fragment added to the 562 * network buffer to store a HTC_FRAME_HDR. 563 * This interface is fully asynchronous. On error, htc_send_data_pkt will 564 * call the registered Endpoint EpDataTxComplete callback to cleanup 565 * the packet. 566 * 567 * Return: QDF_STATUS 568 */ 569 QDF_STATUS htc_send_data_pkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket, 570 uint8_t more_data); 571 #endif /*ATH_11AC_TXCOMPACT */ 572 573 /** 574 * htc_flush_surprise_remove() - Flush HTC when target is removed surprisely 575 * service communications 576 * @HTCHandle: HTC handle 577 * 578 * All receive and pending TX packets will be flushed. 579 * Return: None 580 */ 581 void htc_flush_surprise_remove(HTC_HANDLE HTCHandle); 582 583 /** 584 * htc_stop() - Stop HTC service communications 585 * @HTCHandle: HTC handle 586 * 587 * HTC communications is halted. All receive and pending TX packets 588 * will be flushed. 589 * Return: None 590 */ 591 void htc_stop(HTC_HANDLE HTCHandle); 592 593 /** 594 * htc_destroy() - Destroy HTC service 595 * @HTCHandle: HTC handle 596 * 597 * This cleans up all resources allocated by htc_create(). 598 * Return: None 599 */ 600 void htc_destroy(HTC_HANDLE HTCHandle); 601 602 /** 603 * htc_flush_endpoint() - Flush pending TX packets 604 * @HTCHandle: HTC handle 605 * @Endpoint: Endpoint to flush 606 * @Tag: flush tag 607 * 608 * The Tag parameter is used to selectively flush packets with matching 609 * tags. The value of 0 forces all packets to be flush regardless of tag 610 * Return: None 611 */ 612 void htc_flush_endpoint(HTC_HANDLE HTCHandle, HTC_ENDPOINT_ID Endpoint, 613 HTC_TX_TAG Tag); 614 /** 615 * htc_dump_credit_states() - Dump credit distribution state 616 * @HTCHandle: HTC handle 617 * 618 * This dumps all credit distribution information to the debugger 619 * Return: None 620 */ 621 void htc_dump_credit_states(HTC_HANDLE HTCHandle); 622 623 /** 624 * htc_indicate_activity_change() - Indicate a traffic activity change on an 625 * endpoint 626 * @HTCHandle: HTC handle 627 * @Endpoint: endpoint in which activity has changed 628 * @Active: true if active, false if it has become inactive 629 * 630 * This triggers the registered credit distribution function to 631 * re-adjust credits for active/inactive endpoints. 632 * Return: None 633 */ 634 void htc_indicate_activity_change(HTC_HANDLE HTCHandle, 635 HTC_ENDPOINT_ID Endpoint, bool Active); 636 637 /** 638 * htc_get_endpoint_statistics() - Get endpoint statistics 639 * @HTCHandle: HTC handle 640 * @Endpoint: Endpoint identifier 641 * @Action: action to take with statistics 642 * @pStats: statistics that were sampled (can be NULL if Action is 643 * HTC_EP_STAT_CLEAR) 644 * 645 * Statistics is a compile-time option and this function may return 646 * false if HTC is not compiled with profiling. 647 * The caller can specify the statistic "action" to take when sampling 648 * the statistics. This includes : 649 * HTC_EP_STAT_SAMPLE : The pStats structure is filled with the current 650 * values. 651 * HTC_EP_STAT_SAMPLE_AND_CLEAR : The structure is filled and the current 652 * statisticsare cleared. 653 * HTC_EP_STAT_CLEA : the statistics are cleared, the called can pass 654 * a NULL value for pStats 655 * Return: true if statistics profiling is enabled, otherwise false. 656 */ 657 bool htc_get_endpoint_statistics(HTC_HANDLE HTCHandle, 658 HTC_ENDPOINT_ID Endpoint, 659 enum htc_endpoint_stat_action Action, 660 struct htc_endpoint_stats *pStats); 661 662 /** 663 * htc_unblock_recv() - Unblock HTC message reception 664 * @HTCHandle: HTC handle 665 * 666 * HTC will block the receiver if the EpRecvAlloc callback fails to provide a 667 * packet. The caller can use this API to indicate to HTC when resources 668 * (buffers) are available such that the receiver can be unblocked and HTC 669 * may re-attempt fetching the pending message. 670 * This API is not required if the user uses the EpRecvRefill callback or uses 671 * the HTCAddReceivePacket()API to recycle or provide receive packets to HTC. 672 * Return: None 673 */ 674 void htc_unblock_recv(HTC_HANDLE HTCHandle); 675 676 /** 677 * htc_add_receive_pkt_multiple() - Add multiple receive packets to HTC 678 * @HTCHandle: HTC handle 679 * @pPktQueue: HTC receive packet queue holding packets to add 680 * 681 * User must supply HTC packets for capturing incoming HTC frames. 682 * The caller mmust initialize each HTC packet using the 683 * SET_HTC_PACKET_INFO_RX_REFILL() macro. The queue must only contain 684 * recv packets for the same endpoint. Caller supplies a pointer to an 685 * HTC_PACKET_QUEUE structure holding the recv packet. This API will 686 * remove the packets from the pkt queue and place them into internal 687 * recv packet list. 688 * The caller may allocate the pkt queue on the stack to hold the pkts. 689 * Return: A_OK on success 690 */ 691 A_STATUS htc_add_receive_pkt_multiple(HTC_HANDLE HTCHandle, 692 HTC_PACKET_QUEUE *pPktQueue); 693 694 /** 695 * htc_is_endpoint_active() - Check if an endpoint is marked active 696 * @HTCHandle: HTC handle 697 * @Endpoint: endpoint to check for active state 698 * 699 * Return: returns true if Endpoint is Active 700 */ 701 bool htc_is_endpoint_active(HTC_HANDLE HTCHandle, 702 HTC_ENDPOINT_ID Endpoint); 703 704 /** 705 * htc_set_pkt_dbg() - Set up debug flag for HTC packets 706 * @handle: HTC handle 707 * @dbg_flag: enable or disable flag 708 * 709 * Return: none 710 */ 711 void htc_set_pkt_dbg(HTC_HANDLE handle, A_BOOL dbg_flag); 712 713 /** 714 * htc_set_nodrop_pkt() - Set up nodrop pkt flag for mboxping nodrop pkt 715 * @HTCHandle: HTC handle 716 * @isNodropPkt: indicates whether it is nodrop pkt 717 * 718 * Return: None 719 * 720 */ 721 void htc_set_nodrop_pkt(HTC_HANDLE HTCHandle, A_BOOL isNodropPkt); 722 723 /** 724 * htc_enable_hdr_length_check() - Set up htc_hdr_length_check flag 725 * @htc_handle: HTC handle 726 * @htc_hdr_length_check: flag to indicate whether htc header length check is 727 * required 728 * 729 * Return: None 730 * 731 */ 732 void 733 htc_enable_hdr_length_check(HTC_HANDLE htc_handle, bool htc_hdr_length_check); 734 735 /** 736 * htc_get_num_recv_buffers() - Get the number of recv buffers currently queued 737 * into an HTC endpoint 738 * @HTCHandle: HTC handle 739 * @Endpoint: endpoint to check 740 * 741 * Return: returns number of buffers in queue 742 * 743 */ 744 int htc_get_num_recv_buffers(HTC_HANDLE HTCHandle, 745 HTC_ENDPOINT_ID Endpoint); 746 747 /** 748 * htc_set_target_failure_callback() - Set the target failure handling callback 749 * in HTC layer 750 * @HTCHandle: HTC handle 751 * @Callback: target failure handling callback 752 * 753 * Return: None 754 */ 755 void htc_set_target_failure_callback(HTC_HANDLE HTCHandle, 756 HTC_TARGET_FAILURE Callback); 757 758 /* internally used functions for testing... */ 759 void htc_enable_recv(HTC_HANDLE HTCHandle); 760 void htc_disable_recv(HTC_HANDLE HTCHandle); 761 A_STATUS HTCWaitForPendingRecv(HTC_HANDLE HTCHandle, 762 uint32_t TimeoutInMs, 763 bool *pbIsRecvPending); 764 765 /* function to fetch stats from htc layer*/ 766 struct ol_ath_htc_stats *ieee80211_ioctl_get_htc_stats(HTC_HANDLE 767 HTCHandle); 768 /** 769 * htc_get_tx_queue_depth() - get the tx queue depth of an htc endpoint 770 * @htc_handle: htc handle 771 * @endpoint_id: endpoint to check 772 * 773 * Return: htc_handle tx queue depth 774 */ 775 int htc_get_tx_queue_depth(HTC_HANDLE htc_handle, HTC_ENDPOINT_ID endpoint_id); 776 777 #ifdef WLAN_FEATURE_FASTPATH 778 void htc_ctrl_msg_cmpl(HTC_HANDLE htc_pdev, HTC_ENDPOINT_ID htc_ep_id); 779 780 #define HTC_TX_DESC_FILL(_htc_tx_desc, _download_len, _ep_id, _seq_no) \ 781 do { \ 782 HTC_WRITE32((_htc_tx_desc), \ 783 SM((_download_len), HTC_FRAME_HDR_PAYLOADLEN) | \ 784 SM((_ep_id), HTC_FRAME_HDR_ENDPOINTID)); \ 785 HTC_WRITE32((uint32_t *)(_htc_tx_desc) + 1, \ 786 SM((_seq_no), HTC_FRAME_HDR_CONTROLBYTES1)); \ 787 } while (0) 788 #endif /* WLAN_FEATURE_FASTPATH */ 789 790 #ifdef __cplusplus 791 } 792 #endif 793 void htc_get_control_endpoint_tx_host_credits(HTC_HANDLE HTCHandle, 794 int *credit); 795 void htc_dump_counter_info(HTC_HANDLE HTCHandle); 796 void *htc_get_targetdef(HTC_HANDLE htc_handle); 797 #ifdef FEATURE_RUNTIME_PM 798 int htc_runtime_suspend(HTC_HANDLE htc_ctx); 799 int htc_runtime_resume(HTC_HANDLE htc_ctx); 800 #endif 801 void htc_global_credit_flow_disable(void); 802 void htc_global_credit_flow_enable(void); 803 804 /* Disable ASPM : Disable PCIe low power */ 805 bool htc_can_suspend_link(HTC_HANDLE HTCHandle); 806 807 #ifdef IPA_OFFLOAD 808 void htc_ipa_get_ce_resource(HTC_HANDLE htc_handle, 809 qdf_shared_mem_t **ce_sr, 810 uint32_t *ce_sr_ring_size, 811 qdf_dma_addr_t *ce_reg_paddr); 812 #else 813 #define htc_ipa_get_ce_resource(htc_handle, \ 814 ce_sr, ce_sr_ring_size, ce_reg_paddr) /* NO-OP */ 815 #endif /* IPA_OFFLOAD */ 816 817 #if defined(DEBUG_HL_LOGGING) && defined(CONFIG_HL_SUPPORT) 818 819 /** 820 * htc_dump_bundle_stats() - dump tx and rx htc message bundle stats 821 * @HTCHandle: htc handle 822 * 823 * Return: None 824 */ 825 void htc_dump_bundle_stats(HTC_HANDLE HTCHandle); 826 827 /** 828 * htc_clear_bundle_stats() - clear tx and rx htc message bundle stats 829 * @HTCHandle: htc handle 830 * 831 * Return: None 832 */ 833 void htc_clear_bundle_stats(HTC_HANDLE HTCHandle); 834 #endif 835 836 #ifdef FEATURE_RUNTIME_PM 837 int htc_pm_runtime_get(HTC_HANDLE htc_handle); 838 int htc_pm_runtime_put(HTC_HANDLE htc_handle); 839 840 /** 841 * htc_dec_return_htt_runtime_cnt: Decrement htc htt runtime count 842 * @htc: HTC handle 843 * 844 * Return: value of runtime count after decrement 845 */ 846 int32_t htc_dec_return_htt_runtime_cnt(HTC_HANDLE htc); 847 #else 848 static inline int htc_pm_runtime_get(HTC_HANDLE htc_handle) { return 0; } 849 static inline int htc_pm_runtime_put(HTC_HANDLE htc_handle) { return 0; } 850 851 static inline 852 int32_t htc_dec_return_htt_runtime_cnt(HTC_HANDLE htc) 853 { 854 return -1; 855 } 856 #endif 857 858 #ifdef WLAN_DEBUG_LINK_VOTE 859 /** 860 * htc_log_link_user_votes() - API to log link user votes 861 * 862 * API to log the link user votes 863 * 864 * Return: void 865 */ 866 void htc_log_link_user_votes(void); 867 868 /** 869 * htc_vote_link_down() - API to vote for link down 870 * @htc_handle: HTC handle 871 * @id: PCIe link vote user id 872 * 873 * API for upper layers to call HIF to vote for link down 874 * 875 * Return: void 876 */ 877 void htc_vote_link_down(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id); 878 879 /** 880 * htc_vote_link_up() - API to vote for link up 881 * @htc_handle: HTC Handle 882 * @id: PCIe link vote user id 883 * 884 * API for upper layers to call HIF to vote for link up 885 * 886 * Return: void 887 */ 888 void htc_vote_link_up(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id); 889 890 #else 891 static inline 892 void htc_log_link_user_votes(void) 893 { 894 } 895 896 static inline 897 void htc_vote_link_down(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id) 898 { 899 } 900 901 static inline 902 void htc_vote_link_up(HTC_HANDLE htc_handle, enum htc_link_vote_user_id id) 903 { 904 } 905 #endif 906 907 /** 908 * htc_set_async_ep() - set async HTC end point 909 * user should call this function after htc_connect_service before 910 * queueing any packets to end point 911 * @HTCHandle: htc handle 912 * @htc_ep_id: end point id 913 * @value: true or false 914 * 915 * Return: None 916 */ 917 void htc_set_async_ep(HTC_HANDLE HTCHandle, 918 HTC_ENDPOINT_ID htc_ep_id, bool value); 919 920 /** 921 * htc_set_wmi_endpoint_count: Set number of WMI endpoint 922 * @htc_handle: HTC handle 923 * @wmi_ep_count: WMI endpoint count 924 * 925 * return: None 926 */ 927 void htc_set_wmi_endpoint_count(HTC_HANDLE htc_handle, uint8_t wmi_ep_count); 928 929 /** 930 * htc_get_wmi_endpoint_count: Get number of WMI endpoint 931 * @htc_handle: HTC handle 932 * 933 * return: WMI endpoint count 934 */ 935 uint8_t htc_get_wmi_endpoint_count(HTC_HANDLE htc_handle); 936 937 /** 938 * htc_print_credit_history: print HTC credit history in buffer 939 * @htc: HTC handle 940 * @count: Number of lines to be copied 941 * @print: Print callback to print in the buffer 942 * @print_priv: any data required by the print method, e.g. a file handle 943 * 944 * return: None 945 */ 946 #ifdef FEATURE_HTC_CREDIT_HISTORY 947 void htc_print_credit_history(HTC_HANDLE htc, uint32_t count, 948 qdf_abstract_print * print, void *print_priv); 949 #else 950 static inline 951 void htc_print_credit_history(HTC_HANDLE htc, uint32_t count, 952 qdf_abstract_print *print, void *print_priv) 953 { 954 print(print_priv, "HTC Credit History Feature is disabled"); 955 } 956 #endif 957 958 #ifdef SYSTEM_PM_CHECK 959 /** 960 * htc_system_resume() - Send out any pending WMI/HTT 961 * messages pending in htc queues on system resume. 962 * @htc: HTC handle 963 * 964 * Return: None 965 */ 966 void htc_system_resume(HTC_HANDLE htc); 967 #else 968 static inline void htc_system_resume(HTC_HANDLE htc) 969 { 970 } 971 #endif 972 #endif /* _HTC_API_H_ */ 973