6 * @brief This file contains the public API for the IXP400 NPE Message
11 * IXP400 SW Release version 2.0
13 * -- Copyright Notice --
16 * Copyright 2001-2005, Intel Corporation.
17 * All rights reserved.
20 * Redistribution and use in source and binary forms, with or without
21 * modification, are permitted provided that the following conditions
23 * 1. Redistributions of source code must retain the above copyright
24 * notice, this list of conditions and the following disclaimer.
25 * 2. Redistributions in binary form must reproduce the above copyright
26 * notice, this list of conditions and the following disclaimer in the
27 * documentation and/or other materials provided with the distribution.
28 * 3. Neither the name of the Intel Corporation nor the names of its contributors
29 * may be used to endorse or promote products derived from this software
30 * without specific prior written permission.
33 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
34 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
35 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
36 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
37 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
38 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
39 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
40 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
41 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
42 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46 * -- End of Copyright Notice --
50 * @defgroup IxNpeMh IXP400 NPE Message Handler (IxNpeMh) API
52 * @brief The public API for the IXP400 NPE Message Handler component.
60 #include "IxOsalTypes.h"
63 * #defines for function return types, etc.
66 #define IX_NPEMH_MIN_MESSAGE_ID (0x00) /**< minimum valid message ID */
67 #define IX_NPEMH_MAX_MESSAGE_ID (0xFF) /**< maximum valid message ID */
69 #define IX_NPEMH_SEND_RETRIES_DEFAULT (3) /**< default msg send retries */
73 * @def IX_NPEMH_CRITICAL_NPE_ERR
75 * @brief NpeMH function return value for a Critical NPE error occuring during
76 sending/receiving message. Assume NPE hang / halt if this value is
79 #define IX_NPEMH_CRITICAL_NPE_ERR 2
84 * @brief The ID of a particular NPE.
85 * @note In this context, for IXP425 Silicon (B0):<br>
86 * - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br>
87 * - NPE-B has Ethernet Coprocessor.<br>
88 * - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
89 * - IXP400 Product Line have different combinations of coprocessors.
94 IX_NPEMH_NPEID_NPEA = 0, /**< ID for NPE-A */
95 IX_NPEMH_NPEID_NPEB, /**< ID for NPE-B */
96 IX_NPEMH_NPEID_NPEC, /**< ID for NPE-C */
97 IX_NPEMH_NUM_NPES /**< Number of NPEs */
101 * @enum IxNpeMhNpeInterrupts
103 * @brief Indicator specifying whether or not NPE interrupts should drive
104 * receiving of messages from the NPEs.
109 IX_NPEMH_NPEINTERRUPTS_NO = 0, /**< Don't use NPE interrupts */
110 IX_NPEMH_NPEINTERRUPTS_YES /**< Do use NPE interrupts */
111 } IxNpeMhNpeInterrupts;
114 * @brief The 2-word message structure to send to and receive from the
120 UINT32 data[2]; /**< the actual data of the message */
124 typedef UINT32 IxNpeMhMessageId;
127 * @typedef IxNpeMhCallback
129 * @brief This prototype shows the format of a message callback function.
131 * This prototype shows the format of a message callback function. The
132 * message callback will be passed the message to be handled and will also
133 * be told from which NPE the message was received. The message callback
134 * will either be registered by ixNpeMhUnsolicitedCallbackRegister() or
135 * passed as a parameter to ixNpeMhMessageWithResponseSend(). It will be
136 * called from within an ISR triggered by the NPE's "outFIFO not empty"
137 * interrupt (see ixNpeMhInitialize()). The parameters passed are the ID
138 * of the NPE that the message was received from, and the message to be
139 * handled.<P><B>Re-entrancy:</B> This function is only a prototype, and
140 * will be implemented by the client. It does not need to be re-entrant.
143 typedef void (*IxNpeMhCallback) (IxNpeMhNpeId, IxNpeMhMessage);
146 * Prototypes for interface functions.
152 * @fn IX_STATUS ixNpeMhInitialize (
153 IxNpeMhNpeInterrupts npeInterrupts)
155 * @brief This function will initialise the IxNpeMh component.
157 * @param npeInterrupts @ref IxNpeMhNpeInterrupts [in] - This parameter
158 * dictates whether or not the IxNpeMh component will service NPE "outFIFO
159 * not empty" interrupts to trigger receiving and processing of messages
160 * from the NPEs. If not then the client must use ixNpeMhMessagesReceive()
161 * to control message receiving and processing.
163 * This function will initialise the IxNpeMh component. It should only be
164 * called once, prior to using the IxNpeMh component. The following
165 * actions will be performed by this function:<OL><LI>Initialization of
166 * internal data structures (e.g. solicited and unsolicited callback
167 * tables).</LI><LI>Configuration of the interface with the NPEs (e.g.
168 * enabling of NPE "outFIFO not empty" interrupts).</LI><LI>Registration of
169 * ISRs that will receive and handle messages when the NPEs' "outFIFO not
170 * empty" interrupts fire (if npeInterrupts equals
171 * IX_NPEMH_NPEINTERRUPTS_YES).</LI></OL>
173 * @return The function returns a status indicating success or failure.
176 PUBLIC IX_STATUS ixNpeMhInitialize (
177 IxNpeMhNpeInterrupts npeInterrupts);
182 * @fn IX_STATUS ixNpeMhUnload (void)
184 * @brief This function will uninitialise the IxNpeMh component.
186 * This function will uninitialise the IxNpeMh component. It should only be
187 * called once, and only if the IxNpeMh component has already been initialised.
188 * No other IxNpeMh API functions should be called until @ref ixNpeMhInitialize
190 * If possible, this function should be called before a soft reboot or unloading
191 * a kernel module to perform any clean up operations required for IxNpeMh.
193 * The following actions will be performed by this function:
194 * <OL><LI>Unmapping of kernel memory mapped by the function
195 * @ref ixNpeMhInitialize.</LI></OL>
197 * @return The function returns a status indicating success or failure.
200 PUBLIC IX_STATUS ixNpeMhUnload (void);
205 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
207 IxNpeMhMessageId messageId,
208 IxNpeMhCallback unsolicitedCallback)
210 * @brief This function will register an unsolicited callback for a
211 * particular NPE and message ID.
213 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages
214 * the unsolicited callback will handle.
215 * @param messageId @ref IxNpeMhMessageId [in] - The ID of the messages the
216 * unsolicited callback will handle.
217 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
218 * callback function. A value of NULL will deregister any previously
219 * registered callback for this NPE and message ID.
221 * This function will register an unsolicited message callback for a
222 * particular NPE and message ID.<P>If an unsolicited callback is already
223 * registered for the specified NPE and message ID then the callback will
224 * be overwritten. Only one client will be responsible for handling a
225 * particular message ID associated with a NPE. Registering a NULL
226 * unsolicited callback will deregister any previously registered
227 * callback.<P>The callback function will be called from an ISR that will
228 * be triggered by the NPE's "outFIFO not empty" interrupt (see
229 * ixNpeMhInitialize()) to handle any unsolicited messages of the specific
230 * message ID received from the NPE. Unsolicited messages will be handled
231 * in the order they are received.<P>If no unsolicited callback can be
232 * found for a received message then it is assumed that the message is
233 * solicited.<P>If more than one client may be interested in a particular
234 * unsolicited message then the suggested strategy is to register a
235 * callback for the message that can itself distribute the message to
236 * multiple clients as necessary.<P>See also
237 * ixNpeMhUnsolicitedCallbackForRangeRegister().<P><B>Re-entrancy:</B> This
238 * function will be callable from any thread at any time. IxOsal
239 * will be used for any necessary resource protection.
241 * @return The function returns a status indicating success or failure.
244 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
246 IxNpeMhMessageId messageId,
247 IxNpeMhCallback unsolicitedCallback);
252 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
254 IxNpeMhMessageId minMessageId,
255 IxNpeMhMessageId maxMessageId,
256 IxNpeMhCallback unsolicitedCallback)
258 * @brief This function will register an unsolicited callback for a
259 * particular NPE and range of message IDs.
261 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages the
262 * unsolicited callback will handle.
263 * @param minMessageId @ref IxNpeMhMessageId [in] - The minimum message ID in
264 * the range of message IDs the unsolicited callback will handle.
265 * @param maxMessageId @ref IxNpeMhMessageId [in] - The maximum message ID in
266 * the range of message IDs the unsolicited callback will handle.
267 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
268 * callback function. A value of NULL will deregister any previously
269 * registered callback(s) for this NPE and range of message IDs.
271 * This function will register an unsolicited callback for a particular NPE
272 * and range of message IDs. It is a convenience function that is
273 * effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for
274 * each ID in the specified range. See
275 * ixNpeMhUnsolicitedCallbackRegister() for more
276 * information.<P><B>Re-entrancy:</B> This function will be callable from
277 * any thread at any time. IxOsal will be used for any necessary
278 * resource protection.
280 * @return The function returns a status indicating success or failure.
283 PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
285 IxNpeMhMessageId minMessageId,
286 IxNpeMhMessageId maxMessageId,
287 IxNpeMhCallback unsolicitedCallback);
292 * @fn IX_STATUS ixNpeMhMessageSend (
294 IxNpeMhMessage message,
295 UINT32 maxSendRetries)
297 * @brief This function will send a message to a particular NPE.
299 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
301 * @param message @ref IxNpeMhMessage [in] - The message to send.
302 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
303 * if the NPE's inFIFO is full.
305 * This function will send a message to a particular NPE. It will be the
306 * client's responsibility to ensure that the message is properly formed.
307 * The return status will signify to the client if the message was
308 * successfully sent or not.<P>If the message is sent to the NPE then this
309 * function will return a status of success. Note that this will only mean
310 * the message has been placed in the NPE's inFIFO. There will be no way
311 * of knowing that the NPE has actually read the message, but once in the
312 * incoming message queue it will be safe to assume that the NPE will
314 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
315 * faster than the NPE can handle them. This forces us to retry attempts
316 * to send the message until the NPE services the inFIFO. The client should
317 * specify a ceiling value for the number of retries suitable to their
318 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
319 * the <i>maxSendRetries</i> parameter for this function. Each retry
320 * exceeding this default number will incur a blocking delay of 1 microsecond,
321 * to avoid consuming too much AHB bus bandwidth while performing retries.
322 * <P>Note this function <B>must</B> only be used for messages.
323 * that do not solicit responses. If the message being sent will solicit a
324 * response then the ixNpeMhMessageWithResponseSend() function <B>must</B>
325 * be used to ensure that the response is correctly
326 * handled. <P> This function will return timeout status if NPE hang / halt
327 * while sending message. The timeout error is not related to the
328 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur
329 * if the first word of the message has been sent to NPE (not exceeding
330 * <i>maxSendRetries</i> when sending 1st message word), but the second word of
331 * the message can't be written to NPE's inFIFO due to NPE hang / halt after
332 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES).
333 * <P><B>Re-entrancy:</B> This function will be callable from any
334 * thread at any time. IxOsal will be used for any necessary
335 * resource protection.
337 * @return The function returns a status indicating success, failure or timeout.
340 PUBLIC IX_STATUS ixNpeMhMessageSend (
342 IxNpeMhMessage message,
343 UINT32 maxSendRetries);
348 * @fn IX_STATUS ixNpeMhMessageWithResponseSend (
350 IxNpeMhMessage message,
351 IxNpeMhMessageId solicitedMessageId,
352 IxNpeMhCallback solicitedCallback,
353 UINT32 maxSendRetries)
355 * @brief This function is equivalent to the ixNpeMhMessageSend() function,
356 * but must be used when the message being sent will solicited a response.
358 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
360 * @param message @ref IxNpeMhMessage [in] - The message to send.
361 * @param solicitedMessageId @ref IxNpeMhMessageId [in] - The ID of the
362 * solicited response message.
363 * @param solicitedCallback @ref IxNpeMhCallback [in] - The function to use to
364 * pass the response message back to the client. A value of NULL will
365 * cause the response message to be discarded.
366 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
367 * if the NPE's inFIFO is full.
369 * This function is equivalent to the ixNpeMhMessageSend() function, but
370 * must be used when the message being sent will solicited a
371 * response.<P>The client must specify the ID of the solicited response
372 * message to allow the response to be recognised when it is received. The
373 * client must also specify a callback function to handle the received
374 * response. The IxNpeMh component will not offer the facility to send a
375 * message to a NPE and receive a response within the same context.<P>Note
376 * if the client is not interested in the response, specifying a NULL
377 * callback will cause the response message to be discarded.<P>The
378 * solicited callback will be stored and called some time later from an ISR
379 * that will be triggered by the NPE's "outFIFO not empty" interrupt (see
380 * ixNpeMhInitialize()) to handle the response message corresponding to the
381 * message sent. Response messages will be handled in the order they are
383 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
384 * faster than the NPE can handle them. This forces us to retry attempts
385 * to send the message until the NPE services the inFIFO. The client should
386 * specify a ceiling value for the number of retries suitable to their
387 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
388 * the <i>maxSendRetries</i> parameter for this function. Each retry
389 * exceeding this default number will incur a blocking delay of 1 microsecond,
390 * to avoid consuming too much AHB bus bandwidth while performing retries.
391 * <P> This function will return timeout status if NPE hang / halt
392 * while sending message. The timeout error is not related to the
393 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur
394 * if the first word of the message has been sent to NPE (not exceeding
395 * <i>maxSendRetries</i> when sending 1st message word), but the second word of
396 * the message can't be written to NPE's inFIFO due to NPE hang / halt after
397 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES).
398 * <P><B>Re-entrancy:</B> This function will be callable from any
399 * thread at any time. IxOsal will be used for any necessary
400 * resource protection.
402 * @return The function returns a status indicating success or failure.
405 PUBLIC IX_STATUS ixNpeMhMessageWithResponseSend (
407 IxNpeMhMessage message,
408 IxNpeMhMessageId solicitedMessageId,
409 IxNpeMhCallback solicitedCallback,
410 UINT32 maxSendRetries);
415 * @fn IX_STATUS ixNpeMhMessagesReceive (
418 * @brief This function will receive messages from a particular NPE and
419 * pass each message to the client via a solicited callback (for solicited
420 * messages) or an unsolicited callback (for unsolicited messages).
422 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to receive and
423 * process messages from.
425 * This function will receive messages from a particular NPE and pass each
426 * message to the client via a solicited callback (for solicited messages)
427 * or an unsolicited callback (for unsolicited messages).<P>If the IxNpeMh
428 * component is initialised to service NPE "outFIFO not empty" interrupts
429 * (see ixNpeMhInitialize()) then there is no need to call this function.
430 * This function is only provided as an alternative mechanism to control
431 * the receiving and processing of messages from the NPEs.<P> This function
432 * will return timeout status if NPE hang / halt while receiving message. The
433 * timeout error will only occur if this function has read the first word of
434 * the message and can't read second word of the message from NPE's outFIFO
435 * after maximum retries (IX_NPE_MH_MAX_NUM_OF_RETRIES).
436 * <P>Note this function cannot be called from within
437 * an ISR as it will use resource protection mechanisms.<P><B>Re-entrancy:</B>
438 * This function will be callable from any thread at any time. IxOsal will be
439 * used for any necessary resource protection.
441 * @return The function returns a status indicating success, failure or timeout.
444 PUBLIC IX_STATUS ixNpeMhMessagesReceive (
450 * @fn IX_STATUS ixNpeMhShow (
453 * @brief This function will display the current state of the IxNpeMh
456 * <B>Re-entrancy:</B> This function will be callable from
457 * any thread at any time. However, no resource protection will be used
458 * so as not to impact system performance. As this function is only
459 * reading statistical information then this is acceptable.
461 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to display state
464 * @return The function returns a status indicating success or failure.
467 PUBLIC IX_STATUS ixNpeMhShow (
473 * @fn IX_STATUS ixNpeMhShowReset (
476 * @brief This function will reset the current state of the IxNpeMh
479 * <B>Re-entrancy:</B> This function will be callable from
480 * any thread at any time. However, no resource protection will be used
481 * so as not to impact system performance. As this function is only
482 * writing statistical information then this is acceptable.
484 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to reset state
487 * @return The function returns a status indicating success or failure.
490 PUBLIC IX_STATUS ixNpeMhShowReset (
493 #endif /* IXNPEMH_H */
496 * @} defgroup IxNpeMh