IxNpeMh.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473
  1. /**
  2. * @file IxNpeMh.h
  3. *
  4. * @date 14 Dec 2001
  5. *
  6. * @brief This file contains the public API for the IXP400 NPE Message
  7. * Handler component.
  8. *
  9. *
  10. * @par
  11. * IXP400 SW Release version 2.0
  12. *
  13. * -- Copyright Notice --
  14. *
  15. * @par
  16. * Copyright 2001-2005, Intel Corporation.
  17. * All rights reserved.
  18. *
  19. * @par
  20. * SPDX-License-Identifier: BSD-3-Clause
  21. * @par
  22. * -- End of Copyright Notice --
  23. */
  24. /**
  25. * @defgroup IxNpeMh IXP400 NPE Message Handler (IxNpeMh) API
  26. *
  27. * @brief The public API for the IXP400 NPE Message Handler component.
  28. *
  29. * @{
  30. */
  31. #ifndef IXNPEMH_H
  32. #define IXNPEMH_H
  33. #include "IxOsalTypes.h"
  34. /*
  35. * #defines for function return types, etc.
  36. */
  37. #define IX_NPEMH_MIN_MESSAGE_ID (0x00) /**< minimum valid message ID */
  38. #define IX_NPEMH_MAX_MESSAGE_ID (0xFF) /**< maximum valid message ID */
  39. #define IX_NPEMH_SEND_RETRIES_DEFAULT (3) /**< default msg send retries */
  40. /**
  41. * @def IX_NPEMH_CRITICAL_NPE_ERR
  42. *
  43. * @brief NpeMH function return value for a Critical NPE error occuring during
  44. sending/receiving message. Assume NPE hang / halt if this value is
  45. returned.
  46. */
  47. #define IX_NPEMH_CRITICAL_NPE_ERR 2
  48. /**
  49. * @enum IxNpeMhNpeId
  50. *
  51. * @brief The ID of a particular NPE.
  52. * @note In this context, for IXP425 Silicon (B0):<br>
  53. * - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
  54. * - NPE-B has Ethernet Coprocessor.<br>
  55. * - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
  56. * - IXP400 Product Line have different combinations of coprocessors.
  57. */
  58. typedef enum
  59. {
  60. IX_NPEMH_NPEID_NPEA = 0, /**< ID for NPE-A */
  61. IX_NPEMH_NPEID_NPEB, /**< ID for NPE-B */
  62. IX_NPEMH_NPEID_NPEC, /**< ID for NPE-C */
  63. IX_NPEMH_NUM_NPES /**< Number of NPEs */
  64. } IxNpeMhNpeId;
  65. /**
  66. * @enum IxNpeMhNpeInterrupts
  67. *
  68. * @brief Indicator specifying whether or not NPE interrupts should drive
  69. * receiving of messages from the NPEs.
  70. */
  71. typedef enum
  72. {
  73. IX_NPEMH_NPEINTERRUPTS_NO = 0, /**< Don't use NPE interrupts */
  74. IX_NPEMH_NPEINTERRUPTS_YES /**< Do use NPE interrupts */
  75. } IxNpeMhNpeInterrupts;
  76. /**
  77. * @brief The 2-word message structure to send to and receive from the
  78. * NPEs.
  79. */
  80. typedef struct
  81. {
  82. UINT32 data[2]; /**< the actual data of the message */
  83. } IxNpeMhMessage;
  84. /** message ID */
  85. typedef UINT32 IxNpeMhMessageId;
  86. /**
  87. * @typedef IxNpeMhCallback
  88. *
  89. * @brief This prototype shows the format of a message callback function.
  90. *
  91. * This prototype shows the format of a message callback function. The
  92. * message callback will be passed the message to be handled and will also
  93. * be told from which NPE the message was received. The message callback
  94. * will either be registered by ixNpeMhUnsolicitedCallbackRegister() or
  95. * passed as a parameter to ixNpeMhMessageWithResponseSend(). It will be
  96. * called from within an ISR triggered by the NPE's "outFIFO not empty"
  97. * interrupt (see ixNpeMhInitialize()). The parameters passed are the ID
  98. * of the NPE that the message was received from, and the message to be
  99. * handled.<P><B>Re-entrancy:</B> This function is only a prototype, and
  100. * will be implemented by the client. It does not need to be re-entrant.
  101. */
  102. typedef void (*IxNpeMhCallback) (IxNpeMhNpeId, IxNpeMhMessage);
  103. /*
  104. * Prototypes for interface functions.
  105. */
  106. /**
  107. * @ingroup IxNpeMh
  108. *
  109. * @fn IX_STATUS ixNpeMhInitialize (
  110. IxNpeMhNpeInterrupts npeInterrupts)
  111. *
  112. * @brief This function will initialise the IxNpeMh component.
  113. *
  114. * @param npeInterrupts @ref IxNpeMhNpeInterrupts [in] - This parameter
  115. * dictates whether or not the IxNpeMh component will service NPE "outFIFO
  116. * not empty" interrupts to trigger receiving and processing of messages
  117. * from the NPEs. If not then the client must use ixNpeMhMessagesReceive()
  118. * to control message receiving and processing.
  119. *
  120. * This function will initialise the IxNpeMh component. It should only be
  121. * called once, prior to using the IxNpeMh component. The following
  122. * actions will be performed by this function:<OL><LI>Initialization of
  123. * internal data structures (e.g. solicited and unsolicited callback
  124. * tables).</LI><LI>Configuration of the interface with the NPEs (e.g.
  125. * enabling of NPE "outFIFO not empty" interrupts).</LI><LI>Registration of
  126. * ISRs that will receive and handle messages when the NPEs' "outFIFO not
  127. * empty" interrupts fire (if npeInterrupts equals
  128. * IX_NPEMH_NPEINTERRUPTS_YES).</LI></OL>
  129. *
  130. * @return The function returns a status indicating success or failure.
  131. */
  132. PUBLIC IX_STATUS ixNpeMhInitialize (
  133. IxNpeMhNpeInterrupts npeInterrupts);
  134. /**
  135. * @ingroup IxNpeMh
  136. *
  137. * @fn IX_STATUS ixNpeMhUnload (void)
  138. *
  139. * @brief This function will uninitialise the IxNpeMh component.
  140. *
  141. * This function will uninitialise the IxNpeMh component. It should only be
  142. * called once, and only if the IxNpeMh component has already been initialised.
  143. * No other IxNpeMh API functions should be called until @ref ixNpeMhInitialize
  144. * is called again.
  145. * If possible, this function should be called before a soft reboot or unloading
  146. * a kernel module to perform any clean up operations required for IxNpeMh.
  147. *
  148. * The following actions will be performed by this function:
  149. * <OL><LI>Unmapping of kernel memory mapped by the function
  150. * @ref ixNpeMhInitialize.</LI></OL>
  151. *
  152. * @return The function returns a status indicating success or failure.
  153. */
  154. PUBLIC IX_STATUS ixNpeMhUnload (void);
  155. /**
  156. * @ingroup IxNpeMh
  157. *
  158. * @fn IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
  159. IxNpeMhNpeId npeId,
  160. IxNpeMhMessageId messageId,
  161. IxNpeMhCallback unsolicitedCallback)
  162. *
  163. * @brief This function will register an unsolicited callback for a
  164. * particular NPE and message ID.
  165. *
  166. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages
  167. * the unsolicited callback will handle.
  168. * @param messageId @ref IxNpeMhMessageId [in] - The ID of the messages the
  169. * unsolicited callback will handle.
  170. * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
  171. * callback function. A value of NULL will deregister any previously
  172. * registered callback for this NPE and message ID.
  173. *
  174. * This function will register an unsolicited message callback for a
  175. * particular NPE and message ID.<P>If an unsolicited callback is already
  176. * registered for the specified NPE and message ID then the callback will
  177. * be overwritten. Only one client will be responsible for handling a
  178. * particular message ID associated with a NPE. Registering a NULL
  179. * unsolicited callback will deregister any previously registered
  180. * callback.<P>The callback function will be called from an ISR that will
  181. * be triggered by the NPE's "outFIFO not empty" interrupt (see
  182. * ixNpeMhInitialize()) to handle any unsolicited messages of the specific
  183. * message ID received from the NPE. Unsolicited messages will be handled
  184. * in the order they are received.<P>If no unsolicited callback can be
  185. * found for a received message then it is assumed that the message is
  186. * solicited.<P>If more than one client may be interested in a particular
  187. * unsolicited message then the suggested strategy is to register a
  188. * callback for the message that can itself distribute the message to
  189. * multiple clients as necessary.<P>See also
  190. * ixNpeMhUnsolicitedCallbackForRangeRegister().<P><B>Re-entrancy:</B> This
  191. * function will be callable from any thread at any time. IxOsal
  192. * will be used for any necessary resource protection.
  193. *
  194. * @return The function returns a status indicating success or failure.
  195. */
  196. PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
  197. IxNpeMhNpeId npeId,
  198. IxNpeMhMessageId messageId,
  199. IxNpeMhCallback unsolicitedCallback);
  200. /**
  201. * @ingroup IxNpeMh
  202. *
  203. * @fn IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
  204. IxNpeMhNpeId npeId,
  205. IxNpeMhMessageId minMessageId,
  206. IxNpeMhMessageId maxMessageId,
  207. IxNpeMhCallback unsolicitedCallback)
  208. *
  209. * @brief This function will register an unsolicited callback for a
  210. * particular NPE and range of message IDs.
  211. *
  212. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages the
  213. * unsolicited callback will handle.
  214. * @param minMessageId @ref IxNpeMhMessageId [in] - The minimum message ID in
  215. * the range of message IDs the unsolicited callback will handle.
  216. * @param maxMessageId @ref IxNpeMhMessageId [in] - The maximum message ID in
  217. * the range of message IDs the unsolicited callback will handle.
  218. * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
  219. * callback function. A value of NULL will deregister any previously
  220. * registered callback(s) for this NPE and range of message IDs.
  221. *
  222. * This function will register an unsolicited callback for a particular NPE
  223. * and range of message IDs. It is a convenience function that is
  224. * effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for
  225. * each ID in the specified range. See
  226. * ixNpeMhUnsolicitedCallbackRegister() for more
  227. * information.<P><B>Re-entrancy:</B> This function will be callable from
  228. * any thread at any time. IxOsal will be used for any necessary
  229. * resource protection.
  230. *
  231. * @return The function returns a status indicating success or failure.
  232. */
  233. PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
  234. IxNpeMhNpeId npeId,
  235. IxNpeMhMessageId minMessageId,
  236. IxNpeMhMessageId maxMessageId,
  237. IxNpeMhCallback unsolicitedCallback);
  238. /**
  239. * @ingroup IxNpeMh
  240. *
  241. * @fn IX_STATUS ixNpeMhMessageSend (
  242. IxNpeMhNpeId npeId,
  243. IxNpeMhMessage message,
  244. UINT32 maxSendRetries)
  245. *
  246. * @brief This function will send a message to a particular NPE.
  247. *
  248. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
  249. * to.
  250. * @param message @ref IxNpeMhMessage [in] - The message to send.
  251. * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
  252. * if the NPE's inFIFO is full.
  253. *
  254. * This function will send a message to a particular NPE. It will be the
  255. * client's responsibility to ensure that the message is properly formed.
  256. * The return status will signify to the client if the message was
  257. * successfully sent or not.<P>If the message is sent to the NPE then this
  258. * function will return a status of success. Note that this will only mean
  259. * the message has been placed in the NPE's inFIFO. There will be no way
  260. * of knowing that the NPE has actually read the message, but once in the
  261. * incoming message queue it will be safe to assume that the NPE will
  262. * process it.
  263. * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
  264. * faster than the NPE can handle them. This forces us to retry attempts
  265. * to send the message until the NPE services the inFIFO. The client should
  266. * specify a ceiling value for the number of retries suitable to their
  267. * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
  268. * the <i>maxSendRetries</i> parameter for this function. Each retry
  269. * exceeding this default number will incur a blocking delay of 1 microsecond,
  270. * to avoid consuming too much AHB bus bandwidth while performing retries.
  271. * <P>Note this function <B>must</B> only be used for messages.
  272. * that do not solicit responses. If the message being sent will solicit a
  273. * response then the ixNpeMhMessageWithResponseSend() function <B>must</B>
  274. * be used to ensure that the response is correctly
  275. * handled. <P> This function will return timeout status if NPE hang / halt
  276. * while sending message. The timeout error is not related to the
  277. * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur
  278. * if the first word of the message has been sent to NPE (not exceeding
  279. * <i>maxSendRetries</i> when sending 1st message word), but the second word of
  280. * the message can't be written to NPE's inFIFO due to NPE hang / halt after
  281. * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES).
  282. * <P><B>Re-entrancy:</B> This function will be callable from any
  283. * thread at any time. IxOsal will be used for any necessary
  284. * resource protection.
  285. *
  286. * @return The function returns a status indicating success, failure or timeout.
  287. */
  288. PUBLIC IX_STATUS ixNpeMhMessageSend (
  289. IxNpeMhNpeId npeId,
  290. IxNpeMhMessage message,
  291. UINT32 maxSendRetries);
  292. /**
  293. * @ingroup IxNpeMh
  294. *
  295. * @fn IX_STATUS ixNpeMhMessageWithResponseSend (
  296. IxNpeMhNpeId npeId,
  297. IxNpeMhMessage message,
  298. IxNpeMhMessageId solicitedMessageId,
  299. IxNpeMhCallback solicitedCallback,
  300. UINT32 maxSendRetries)
  301. *
  302. * @brief This function is equivalent to the ixNpeMhMessageSend() function,
  303. * but must be used when the message being sent will solicited a response.
  304. *
  305. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
  306. * to.
  307. * @param message @ref IxNpeMhMessage [in] - The message to send.
  308. * @param solicitedMessageId @ref IxNpeMhMessageId [in] - The ID of the
  309. * solicited response message.
  310. * @param solicitedCallback @ref IxNpeMhCallback [in] - The function to use to
  311. * pass the response message back to the client. A value of NULL will
  312. * cause the response message to be discarded.
  313. * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
  314. * if the NPE's inFIFO is full.
  315. *
  316. * This function is equivalent to the ixNpeMhMessageSend() function, but
  317. * must be used when the message being sent will solicited a
  318. * response.<P>The client must specify the ID of the solicited response
  319. * message to allow the response to be recognised when it is received. The
  320. * client must also specify a callback function to handle the received
  321. * response. The IxNpeMh component will not offer the facility to send a
  322. * message to a NPE and receive a response within the same context.<P>Note
  323. * if the client is not interested in the response, specifying a NULL
  324. * callback will cause the response message to be discarded.<P>The
  325. * solicited callback will be stored and called some time later from an ISR
  326. * that will be triggered by the NPE's "outFIFO not empty" interrupt (see
  327. * ixNpeMhInitialize()) to handle the response message corresponding to the
  328. * message sent. Response messages will be handled in the order they are
  329. * received.<P>
  330. * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
  331. * faster than the NPE can handle them. This forces us to retry attempts
  332. * to send the message until the NPE services the inFIFO. The client should
  333. * specify a ceiling value for the number of retries suitable to their
  334. * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
  335. * the <i>maxSendRetries</i> parameter for this function. Each retry
  336. * exceeding this default number will incur a blocking delay of 1 microsecond,
  337. * to avoid consuming too much AHB bus bandwidth while performing retries.
  338. * <P> This function will return timeout status if NPE hang / halt
  339. * while sending message. The timeout error is not related to the
  340. * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur
  341. * if the first word of the message has been sent to NPE (not exceeding
  342. * <i>maxSendRetries</i> when sending 1st message word), but the second word of
  343. * the message can't be written to NPE's inFIFO due to NPE hang / halt after
  344. * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES).
  345. * <P><B>Re-entrancy:</B> This function will be callable from any
  346. * thread at any time. IxOsal will be used for any necessary
  347. * resource protection.
  348. *
  349. * @return The function returns a status indicating success or failure.
  350. */
  351. PUBLIC IX_STATUS ixNpeMhMessageWithResponseSend (
  352. IxNpeMhNpeId npeId,
  353. IxNpeMhMessage message,
  354. IxNpeMhMessageId solicitedMessageId,
  355. IxNpeMhCallback solicitedCallback,
  356. UINT32 maxSendRetries);
  357. /**
  358. * @ingroup IxNpeMh
  359. *
  360. * @fn IX_STATUS ixNpeMhMessagesReceive (
  361. IxNpeMhNpeId npeId)
  362. *
  363. * @brief This function will receive messages from a particular NPE and
  364. * pass each message to the client via a solicited callback (for solicited
  365. * messages) or an unsolicited callback (for unsolicited messages).
  366. *
  367. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to receive and
  368. * process messages from.
  369. *
  370. * This function will receive messages from a particular NPE and pass each
  371. * message to the client via a solicited callback (for solicited messages)
  372. * or an unsolicited callback (for unsolicited messages).<P>If the IxNpeMh
  373. * component is initialised to service NPE "outFIFO not empty" interrupts
  374. * (see ixNpeMhInitialize()) then there is no need to call this function.
  375. * This function is only provided as an alternative mechanism to control
  376. * the receiving and processing of messages from the NPEs.<P> This function
  377. * will return timeout status if NPE hang / halt while receiving message. The
  378. * timeout error will only occur if this function has read the first word of
  379. * the message and can't read second word of the message from NPE's outFIFO
  380. * after maximum retries (IX_NPE_MH_MAX_NUM_OF_RETRIES).
  381. * <P>Note this function cannot be called from within
  382. * an ISR as it will use resource protection mechanisms.<P><B>Re-entrancy:</B>
  383. * This function will be callable from any thread at any time. IxOsal will be
  384. * used for any necessary resource protection.
  385. *
  386. * @return The function returns a status indicating success, failure or timeout.
  387. */
  388. PUBLIC IX_STATUS ixNpeMhMessagesReceive (
  389. IxNpeMhNpeId npeId);
  390. /**
  391. * @ingroup IxNpeMh
  392. *
  393. * @fn IX_STATUS ixNpeMhShow (
  394. IxNpeMhNpeId npeId)
  395. *
  396. * @brief This function will display the current state of the IxNpeMh
  397. * component.
  398. *
  399. * <B>Re-entrancy:</B> This function will be callable from
  400. * any thread at any time. However, no resource protection will be used
  401. * so as not to impact system performance. As this function is only
  402. * reading statistical information then this is acceptable.
  403. *
  404. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to display state
  405. * information for.
  406. *
  407. * @return The function returns a status indicating success or failure.
  408. */
  409. PUBLIC IX_STATUS ixNpeMhShow (
  410. IxNpeMhNpeId npeId);
  411. /**
  412. * @ingroup IxNpeMh
  413. *
  414. * @fn IX_STATUS ixNpeMhShowReset (
  415. IxNpeMhNpeId npeId)
  416. *
  417. * @brief This function will reset the current state of the IxNpeMh
  418. * component.
  419. *
  420. * <B>Re-entrancy:</B> This function will be callable from
  421. * any thread at any time. However, no resource protection will be used
  422. * so as not to impact system performance. As this function is only
  423. * writing statistical information then this is acceptable.
  424. *
  425. * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to reset state
  426. * information for.
  427. *
  428. * @return The function returns a status indicating success or failure.
  429. */
  430. PUBLIC IX_STATUS ixNpeMhShowReset (
  431. IxNpeMhNpeId npeId);
  432. #endif /* IXNPEMH_H */
  433. /**
  434. * @} defgroup IxNpeMh
  435. */