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