htc_api.h 34 KB

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