summaryrefslogtreecommitdiff
path: root/cpu/ixp/npe/include/IxNpeMh.h
blob: 20ee38b0628ca26a99869913ee213b944009cc59 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
/**
 * @file IxNpeMh.h
 *
 * @date 14 Dec 2001
 *
 * @brief This file contains the public API for the IXP400 NPE Message
 * Handler component.
 *
 * 
 * @par
 * IXP400 SW Release version 2.0
 * 
 * -- Copyright Notice --
 * 
 * @par
 * Copyright 2001-2005, Intel Corporation.
 * All rights reserved.
 * 
 * @par
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Intel Corporation nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 * @par
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * 
 * @par
 * -- End of Copyright Notice --
*/

/**
 * @defgroup IxNpeMh IXP400 NPE Message Handler (IxNpeMh) API
 *
 * @brief The public API for the IXP400 NPE Message Handler component.
 * 
 * @{
 */

#ifndef IXNPEMH_H
#define IXNPEMH_H

#include "IxOsalTypes.h"

/*
 * #defines for function return types, etc.
 */

#define IX_NPEMH_MIN_MESSAGE_ID (0x00) /**< minimum valid message ID */
#define IX_NPEMH_MAX_MESSAGE_ID (0xFF) /**< maximum valid message ID */

#define IX_NPEMH_SEND_RETRIES_DEFAULT (3) /**< default msg send retries */


/**
 * @def IX_NPEMH_CRITICAL_NPE_ERR
 *
 * @brief NpeMH function return value for a Critical NPE error occuring during
          sending/receiving message. Assume NPE hang / halt if this value is
          returned.
 */
#define IX_NPEMH_CRITICAL_NPE_ERR        2

/**
 * @enum IxNpeMhNpeId
 *
 * @brief The ID of a particular NPE.
 * @note In this context, for IXP425 Silicon (B0):<br> 
 *      - NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.<br> 
 *      - NPE-B has Ethernet Coprocessor.<br>
 *      - NPE-C has Ethernet, AES, DES and HASH Coprocessors.<br>
 *      - IXP400 Product Line have different combinations of coprocessors. 
 */

typedef enum
{
    IX_NPEMH_NPEID_NPEA = 0, /**< ID for NPE-A */
    IX_NPEMH_NPEID_NPEB,     /**< ID for NPE-B */
    IX_NPEMH_NPEID_NPEC,     /**< ID for NPE-C */
    IX_NPEMH_NUM_NPES        /**< Number of NPEs */
} IxNpeMhNpeId;

/**
 * @enum IxNpeMhNpeInterrupts
 *
 * @brief Indicator specifying whether or not NPE interrupts should drive
 * receiving of messages from the NPEs.
 */

typedef enum
{
    IX_NPEMH_NPEINTERRUPTS_NO = 0, /**< Don't use NPE interrupts */
    IX_NPEMH_NPEINTERRUPTS_YES     /**< Do use NPE interrupts */
} IxNpeMhNpeInterrupts;

/**
 * @brief The 2-word message structure to send to and receive from the
 * NPEs.
 */

typedef struct
{
    UINT32 data[2]; /**< the actual data of the message */
} IxNpeMhMessage;

/** message ID */
typedef UINT32 IxNpeMhMessageId;

/**
 * @typedef IxNpeMhCallback
 *
 * @brief This prototype shows the format of a message callback function.
 *
 * This prototype shows the format of a message callback function.  The
 * message callback will be passed the message to be handled and will also
 * be told from which NPE the message was received.  The message callback
 * will either be registered by ixNpeMhUnsolicitedCallbackRegister() or
 * passed as a parameter to ixNpeMhMessageWithResponseSend().  It will be
 * called from within an ISR triggered by the NPE's "outFIFO not empty"
 * interrupt (see ixNpeMhInitialize()).  The parameters passed are the ID
 * of the NPE that the message was received from, and the message to be
 * handled.<P><B>Re-entrancy:</B> This function is only a prototype, and
 * will be implemented by the client.  It does not need to be re-entrant.
 */

typedef void (*IxNpeMhCallback) (IxNpeMhNpeId, IxNpeMhMessage);

/*
 * Prototypes for interface functions.
 */

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhInitialize (
           IxNpeMhNpeInterrupts npeInterrupts)
 *
 * @brief This function will initialise the IxNpeMh component.
 *
 * @param npeInterrupts @ref IxNpeMhNpeInterrupts [in] - This parameter
 * dictates whether or not the IxNpeMh component will service NPE "outFIFO
 * not empty" interrupts to trigger receiving and processing of messages
 * from the NPEs.  If not then the client must use ixNpeMhMessagesReceive()
 * to control message receiving and processing.
 *
 * This function will initialise the IxNpeMh component.  It should only be
 * called once, prior to using the IxNpeMh component.  The following
 * actions will be performed by this function:<OL><LI>Initialization of
 * internal data structures (e.g. solicited and unsolicited callback
 * tables).</LI><LI>Configuration of the interface with the NPEs (e.g.
 * enabling of NPE "outFIFO not empty" interrupts).</LI><LI>Registration of
 * ISRs that will receive and handle messages when the NPEs' "outFIFO not
 * empty" interrupts fire (if npeInterrupts equals
 * IX_NPEMH_NPEINTERRUPTS_YES).</LI></OL>
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhInitialize (
    IxNpeMhNpeInterrupts npeInterrupts);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhUnload (void)
 *
 * @brief This function will uninitialise the IxNpeMh component.
 *
 * This function will uninitialise the IxNpeMh component.  It should only be
 * called once, and only if the IxNpeMh component has already been initialised.
 * No other IxNpeMh API functions should be called until @ref ixNpeMhInitialize
 * is called again.
 * If possible, this function should be called before a soft reboot or unloading
 * a kernel module to perform any clean up operations required for IxNpeMh.
 *
 * The following actions will be performed by this function:
 * <OL><LI>Unmapping of kernel memory mapped by the function
 * @ref ixNpeMhInitialize.</LI></OL>
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhUnload (void);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
           IxNpeMhNpeId npeId,
           IxNpeMhMessageId messageId,
           IxNpeMhCallback unsolicitedCallback)
 *
 * @brief This function will register an unsolicited callback for a
 * particular NPE and message ID.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages
 * the unsolicited callback will handle.
 * @param messageId @ref IxNpeMhMessageId [in] - The ID of the messages the
 * unsolicited callback will handle.
 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
 * callback function.  A value of NULL will deregister any previously
 * registered callback for this NPE and message ID.
 *
 * This function will register an unsolicited message callback for a
 * particular NPE and message ID.<P>If an unsolicited callback is already
 * registered for the specified NPE and message ID then the callback will
 * be overwritten.  Only one client will be responsible for handling a
 * particular message ID associated with a NPE.  Registering a NULL
 * unsolicited callback will deregister any previously registered
 * callback.<P>The callback function will be called from an ISR that will
 * be triggered by the NPE's "outFIFO not empty" interrupt (see
 * ixNpeMhInitialize()) to handle any unsolicited messages of the specific
 * message ID received from the NPE.  Unsolicited messages will be handled
 * in the order they are received.<P>If no unsolicited callback can be
 * found for a received message then it is assumed that the message is
 * solicited.<P>If more than one client may be interested in a particular
 * unsolicited message then the suggested strategy is to register a
 * callback for the message that can itself distribute the message to
 * multiple clients as necessary.<P>See also
 * ixNpeMhUnsolicitedCallbackForRangeRegister().<P><B>Re-entrancy:</B> This
 * function will be callable from any thread at any time.  IxOsal
 * will be used for any necessary resource protection.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackRegister (
    IxNpeMhNpeId npeId,
    IxNpeMhMessageId messageId,
    IxNpeMhCallback unsolicitedCallback);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
           IxNpeMhNpeId npeId,
           IxNpeMhMessageId minMessageId,
           IxNpeMhMessageId maxMessageId,
           IxNpeMhCallback unsolicitedCallback)
 *
 * @brief This function will register an unsolicited callback for a
 * particular NPE and range of message IDs.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE whose messages the
 * unsolicited callback will handle.
 * @param minMessageId @ref IxNpeMhMessageId [in] - The minimum message ID in
 * the range of message IDs the unsolicited callback will handle.
 * @param maxMessageId @ref IxNpeMhMessageId [in] - The maximum message ID in
 * the range of message IDs the unsolicited callback will handle.
 * @param unsolicitedCallback @ref IxNpeMhCallback [in] - The unsolicited
 * callback function.  A value of NULL will deregister any previously
 * registered callback(s) for this NPE and range of message IDs.
 *
 * This function will register an unsolicited callback for a particular NPE
 * and range of message IDs.  It is a convenience function that is
 * effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for
 * each ID in the specified range.  See
 * ixNpeMhUnsolicitedCallbackRegister() for more
 * information.<P><B>Re-entrancy:</B> This function will be callable from
 * any thread at any time.  IxOsal will be used for any necessary
 * resource protection.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (
    IxNpeMhNpeId npeId,
    IxNpeMhMessageId minMessageId,
    IxNpeMhMessageId maxMessageId,
    IxNpeMhCallback unsolicitedCallback);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhMessageSend (
           IxNpeMhNpeId npeId,
           IxNpeMhMessage message,
           UINT32 maxSendRetries)
 *
 * @brief This function will send a message to a particular NPE.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
 * to.
 * @param message @ref IxNpeMhMessage [in] - The message to send.
 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
 * if the NPE's inFIFO is full.
 *
 * This function will send a message to a particular NPE.  It will be the
 * client's responsibility to ensure that the message is properly formed.
 * The return status will signify to the client if the message was
 * successfully sent or not.<P>If the message is sent to the NPE then this
 * function will return a status of success.  Note that this will only mean
 * the message has been placed in the NPE's inFIFO.  There will be no way
 * of knowing that the NPE has actually read the message, but once in the
 * incoming message queue it will be safe to assume that the NPE will
 * process it.
 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
 * faster than the NPE can handle them. This forces us to retry attempts 
 * to send the message until the NPE services the inFIFO. The client should
 * specify a ceiling value for the number of retries suitable to their
 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
 * the <i>maxSendRetries</i> parameter for this function. Each retry
 * exceeding this default number will incur a blocking delay of 1 microsecond,
 * to avoid consuming too much AHB bus bandwidth while performing retries.
 * <P>Note this function <B>must</B> only be used for messages.
 * that do not solicit responses. If the message being sent will solicit a
 * response then the ixNpeMhMessageWithResponseSend() function <B>must</B>
 * be used to ensure that the response is correctly
 * handled. <P> This function will return timeout status if NPE hang / halt 
 * while sending message. The timeout error is not related to the 
 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur 
 * if the first word of the message has been sent to NPE (not exceeding 
 * <i>maxSendRetries</i> when sending 1st message word), but the second word of
 * the message can't be written to NPE's inFIFO due to NPE hang / halt after 
 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES). 
 * <P><B>Re-entrancy:</B> This function will be callable from any
 * thread at any time.  IxOsal will be used for any necessary
 * resource protection.
 *
 * @return The function returns a status indicating success, failure or timeout.
 */

PUBLIC IX_STATUS ixNpeMhMessageSend (
    IxNpeMhNpeId npeId,
    IxNpeMhMessage message,
    UINT32 maxSendRetries);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhMessageWithResponseSend (
           IxNpeMhNpeId npeId,
           IxNpeMhMessage message,
           IxNpeMhMessageId solicitedMessageId,
           IxNpeMhCallback solicitedCallback,
           UINT32 maxSendRetries)
 *
 * @brief This function is equivalent to the ixNpeMhMessageSend() function,
 * but must be used when the message being sent will solicited a response.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to send the message
 * to.
 * @param message @ref IxNpeMhMessage [in] - The message to send.
 * @param solicitedMessageId @ref IxNpeMhMessageId [in] - The ID of the
 * solicited response message.
 * @param solicitedCallback @ref IxNpeMhCallback [in] - The function to use to
 * pass the response message back to the client.  A value of NULL will
 * cause the response message to be discarded.
 * @param maxSendRetries UINT32 [in] - Max num. of retries to perform
 * if the NPE's inFIFO is full.
 *
 * This function is equivalent to the ixNpeMhMessageSend() function, but
 * must be used when the message being sent will solicited a
 * response.<P>The client must specify the ID of the solicited response
 * message to allow the response to be recognised when it is received.  The
 * client must also specify a callback function to handle the received
 * response.  The IxNpeMh component will not offer the facility to send a
 * message to a NPE and receive a response within the same context.<P>Note
 * if the client is not interested in the response, specifying a NULL
 * callback will cause the response message to be discarded.<P>The
 * solicited callback will be stored and called some time later from an ISR
 * that will be triggered by the NPE's "outFIFO not empty" interrupt (see
 * ixNpeMhInitialize()) to handle the response message corresponding to the
 * message sent.  Response messages will be handled in the order they are
 * received.<P>
 * <P>The inFIFO may fill up sometimes if the Xscale is sending messages
 * faster than the NPE can handle them. This forces us to retry attempts 
 * to send the message until the NPE services the inFIFO. The client should
 * specify a ceiling value for the number of retries suitable to their
 * needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for
 * the <i>maxSendRetries</i> parameter for this function. Each retry
 * exceeding this default number will incur a blocking delay of 1 microsecond,
 * to avoid consuming too much AHB bus bandwidth while performing retries.
 * <P> This function will return timeout status if NPE hang / halt 
 * while sending message. The timeout error is not related to the 
 * <i>maxSendRetries</i> as mentioned above. The timeout error will only occur 
 * if the first word of the message has been sent to NPE (not exceeding 
 * <i>maxSendRetries</i> when sending 1st message word), but the second word of
 * the message can't be written to NPE's inFIFO due to NPE hang / halt after 
 * maximum waiting time (IX_NPE_MH_MAX_NUM_OF_RETRIES). 
 * <P><B>Re-entrancy:</B> This function will be callable from any
 * thread at any time.  IxOsal will be used for any necessary
 * resource protection.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhMessageWithResponseSend (
    IxNpeMhNpeId npeId,
    IxNpeMhMessage message,
    IxNpeMhMessageId solicitedMessageId,
    IxNpeMhCallback solicitedCallback,
    UINT32 maxSendRetries);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhMessagesReceive (
           IxNpeMhNpeId npeId)
 *
 * @brief This function will receive messages from a particular NPE and
 * pass each message to the client via a solicited callback (for solicited
 * messages) or an unsolicited callback (for unsolicited messages).
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to receive and
 * process messages from.
 *
 * This function will receive messages from a particular NPE and pass each
 * message to the client via a solicited callback (for solicited messages)
 * or an unsolicited callback (for unsolicited messages).<P>If the IxNpeMh
 * component is initialised to service NPE "outFIFO not empty" interrupts
 * (see ixNpeMhInitialize()) then there is no need to call this function.
 * This function is only provided as an alternative mechanism to control
 * the receiving and processing of messages from the NPEs.<P> This function
 * will return timeout status if NPE hang / halt while receiving message. The
 * timeout error will only occur if this function has read the first word of
 * the message and can't read second word of the message from NPE's outFIFO
 * after maximum retries (IX_NPE_MH_MAX_NUM_OF_RETRIES). 
 * <P>Note this function cannot be called from within 
 * an ISR as it will use resource protection mechanisms.<P><B>Re-entrancy:</B> 
 * This function will be callable from any thread at any time.  IxOsal will be 
 * used for any necessary resource protection.
 *
 * @return The function returns a status indicating success, failure or timeout.
 */

PUBLIC IX_STATUS ixNpeMhMessagesReceive (
    IxNpeMhNpeId npeId);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhShow (
           IxNpeMhNpeId npeId)
 *
 * @brief This function will display the current state of the IxNpeMh
 * component.
 *
 * <B>Re-entrancy:</B> This function will be callable from
 * any thread at any time.  However, no resource protection will be used
 * so as not to impact system performance.  As this function is only
 * reading statistical information then this is acceptable.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to display state
 * information for.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhShow (
    IxNpeMhNpeId npeId);

/**
 * @ingroup IxNpeMh
 *
 * @fn IX_STATUS ixNpeMhShowReset (
           IxNpeMhNpeId npeId)
 *
 * @brief This function will reset the current state of the IxNpeMh
 * component.
 *
 * <B>Re-entrancy:</B> This function will be callable from
 * any thread at any time.  However, no resource protection will be used
 * so as not to impact system performance.  As this function is only
 * writing statistical information then this is acceptable.
 *
 * @param npeId @ref IxNpeMhNpeId [in] - The ID of the NPE to reset state
 * information for.
 *
 * @return The function returns a status indicating success or failure.
 */

PUBLIC IX_STATUS ixNpeMhShowReset (
    IxNpeMhNpeId npeId);

#endif /* IXNPEMH_H */

/**
 * @} defgroup IxNpeMh
 */