htc_api.h 31 KB

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