source: SVN/cambria/redboot/packages/devs/eth/intel/npe/common/current/include/IxErrHdlAcc.h @ 1

Last change on this file since 1 was 1, checked in by Tim Harvey, 2 years ago

restored latest version of files from server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 15.4 KB
Line 
1/**
2 * @file    IxErrHdlAcc.h
3 *
4 * @brief this file contains the public API of @ref IxErrHdlAcc component
5 *
6 * @par
7 * IXP400 SW Release version 2.3
8 *
9 * -- Copyright Notice --
10 *
11 * @par
12 * Copyright (c) 2001-2005, Intel Corporation.
13 * All rights reserved.
14 *
15 * @par
16 * Redistribution and use in source and binary forms, with or without
17 * modification, are permitted provided that the following conditions
18 * are met:
19 * 1. Redistributions of source code must retain the above copyright
20 *    notice, this list of conditions and the following disclaimer.
21 * 2. Redistributions in binary form must reproduce the above copyright
22 *    notice, this list of conditions and the following disclaimer in the
23 *    documentation and/or other materials provided with the distribution.
24 * 3. Neither the name of the Intel Corporation nor the names of its contributors
25 *    may be used to endorse or promote products derived from this software
26 *    without specific prior written permission.
27 *
28 *
29 * @par
30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
31 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
32 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
34 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
35 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
36 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
37 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
38 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
39 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
40 * SUCH DAMAGE.
41 *
42 *
43 * @par
44 * -- End of Copyright Notice --
45 */
46
47/*
48 * Put the user defined include files required
49 */
50#ifndef IxErrHdlAcc_H
51#define IxErrHdlAcc_H
52#include "IxOsal.h"
53 /**
54 * @defgroup IxErrHdlAcc IXP400 Soft-Error Handler Driver (ixErrHdlAcc) API
55 *
56 * @brief The public API  for the IXP400 Soft-Error Handler Driver (ixErrHdlAcc)
57 *
58 * @{
59 */
60
61 /**
62 * @ingroup IxErrHdlAcc
63 * @enum IxErrHdlAccErrorEventType
64 * @brief Definition of the Soft-Error Event Types
65 */
66typedef enum{
67 IX_ERRHDLACC_NPEA_ERROR,  /* 0*/
68 IX_ERRHDLACC_NPEB_ERROR,  /* 1*/
69 IX_ERRHDLACC_NPEC_ERROR,  /* 2*/
70 IX_ERRHDLACC_AQM_ERROR,   /* 3*/
71 IX_ERRHDLACC_NO_ERROR     /* 4*/
72}IxErrHdlAccErrorEventType;
73
74/**
75 * @ingroup IxErrHdlAcc
76 * @brief Definition of the NPE A Error Mask Bit
77 */
78#define IX_ERRHDLACC_NPEA_ERROR_MASK_BIT            (1<<IX_ERRHDLACC_NPEA_ERROR)
79
80/**
81 * @ingroup IxErrHdlAcc
82 * @brief Definition of the NPE B Error Mask Bit
83 */
84#define IX_ERRHDLACC_NPEB_ERROR_MASK_BIT            (1<<IX_ERRHDLACC_NPEB_ERROR)
85
86/**
87 * @ingroup IxErrHdlAcc
88 * @brief Definition of the NPE C Error Mask Bit
89 */
90#define IX_ERRHDLACC_NPEC_ERROR_MASK_BIT            (1<<IX_ERRHDLACC_NPEC_ERROR)
91
92/**
93 * @ingroup IxErrHdlAcc
94 * @brief Definition of the AQM Error Mask Bit
95 */
96#define IX_ERRHDLACC_AQM_SRAM_PARITY_ERROR_MASK_BIT (1<<IX_ERRHDLACC_AQM_ERROR)
97
98
99/**
100 * @ingroup IxErrHdlAcc
101 * @enum IxErrHdlAccNPEId
102 * @brief Definition of the NPE ID
103 */
104typedef enum{
105 IX_ERRHDLACC_NPEA, /* 0*/
106 IX_ERRHDLACC_NPEB, /* 1*/
107 IX_ERRHDLACC_NPEC  /* 2*/
108}IxErrHdlAccNPEId;
109
110/**
111 * @ingroup IxErrHdlAcc
112 * @enum IxErrHdlAccEnableEvent
113 * @brief Definition of the Soft-Error Event Enable/Disable
114 */
115typedef enum{
116  IX_ERRHDLACC_EVT_DISABLE = 0, /* Disable the Event handling*/ 
117  IX_ERRHDLACC_EVT_ENABLE       /* Enalbe the Event handling*/
118}IxErrHdlAccEnableEvent;
119
120/**
121 * @ingroup IxErrHdlAcc
122 * @typedef IxErrHdlAccRecoveryDoneCallback
123 * @brief Definition of the Recovery Done Call-back type Function pointer
124 * with IxErrHdlAccErrorEventType type as the argument.
125 */
126typedef void (*IxErrHdlAccRecoveryDoneCallback)(IxErrHdlAccErrorEventType);
127
128/**
129 * @ingroup IxErrHdlAcc
130 * @typedef IxErrHdlAccFuncHandler
131 * @brief Definition of the Event handler type function pointer
132 */
133typedef IX_STATUS (*IxErrHdlAccFuncHandler)(void);
134
135 /**
136 * @brief Debug Statistical Data Structure
137 */
138typedef struct{
139
140 UINT32 totalNPEAEvent;      /* Total NPE A Error Events*/
141 UINT32 totalNPEBEvent;      /* Total NPE B Error Events*/
142 UINT32 totalNPECEvent;      /* Total NPE C Error Events*/
143 UINT32 totalAQMEvent;       /* Total AQM Error Events */
144 UINT32 totalNPEARecoveryPass; 
145 UINT32 totalNPEBRecoveryPass; 
146 UINT32 totalNPECRecoveryPass;
147 UINT32 totalAQMRecoveryPass;
148}IxErrHdlAccRecoveryStatistics;
149
150/**
151 * @ingroup IxErrHdlAcc
152 *
153 * @fn IX_STATUS ixErrHdlAccEnableConfigGet (UINT32* configMask)
154 *
155 *
156 * @brief Gets the configuration word enable setup.
157 
158 * @note
159 *    This API gets the soft-error configuration setup in the module
160 *    that was set by the call to the @ref ixErrHdlAccEnableConfigSet API.
161 *
162 * - Reentrant    - no
163 * - ISR Callable - yes
164 *
165 * @pre The ixErrHdlAcc module should have already
166 *      been intialized prior to calling this API.
167 *   
168 * @param configMask UINT32* [in] Data UINT32 pointer to store
169 * the configuration Mask whereby, any bits set or clear indicates
170 * an enable or disable of a particular Error event type.
171 *                               
172 *
173 *
174 * @return IX_STATUS
175 * - IX_SUCCESS: Operation success
176 * - IX_FAIL : An uninitialized ixErrHdlAcc module or
177 *             a NULL pointer provided to the 1st
178               parameter argument of the function.
179 *
180 * @sa ixErrHdlAccEnableConfigSet
181 * <hr>
182 */
183PUBLIC IX_STATUS ixErrHdlAccEnableConfigGet(UINT32* configMask);
184
185/**
186 * @ingroup IxErrHdlAcc
187 *
188 * @fn IX_STATUS ixErrHdlAccEnableConfigSet(UINT32 configMask)
189 *
190 *
191 * @brief Configures the ixErrHdlAcc module's configuration,
192 *        to enable or disable a maximum total of 32 Soft Error Events
193 *        types.
194 * - Reentrant    - no
195 * - ISR Callable - yes
196 *
197 * @note
198 *    @n An example to enable NPE A , NPE B and NPE C Error handling.
199 *    @n ixErrHdlAccEnableConfigSet(IX_ERRHDLACC_NPEA_ERROR_MASK_BIT
200 *                            @n |IX_ERRHDLACC_NPEB_ERROR_MASK_BIT
201 *                            @n |IX_ERRHDLACC_NPEC_ERROR_MASK_BIT);
202 *
203 * @pre ixErrHdlAcc must be initialized by calling the
204        ixErrHdlAccInit prior to using this API.
205 *   
206 * @param configMask UINT32 [in] - a 32 bit Configuration word
207          where a bit N set will enable the event N
208                a bit N clear will disable the event N
209                N=0, 1, 2, ...31.
210 *
211 * @return IX_STATUS
212 * - IX_SUCCESS: Operation success
213 * - IX_FAIL : A fail if the module is not initialized.
214 *
215 * @sa ixErrHdlAccEnableConfigGet
216 * <hr>
217 */
218PUBLIC IX_STATUS ixErrHdlAccEnableConfigSet(UINT32 configMask);
219
220/**
221 * @ingroup IxErrHdlAcc
222 *
223 * @fn IX_STATUS ixErrHdlAccNPEReset(IxErrHdlAccNPEId npeID)
224 *
225 *
226 * @brief Reset the NPE via the  Expansion bus
227 * controller FUSE register. The API sets the FUSE Bit that
228 * resets the NPE. It waits for the NPE to reset and then,
229 * turns off the FUSE bit to re-enable the NPE.
230 *
231 *
232 * - Reentrant    - yes
233 * - ISR Callable - yes
234 *
235 * @pre npeID must be a valid NPE ID where,
236    0 - NPEA, 1 - NPEB & 2 - NPEC
237 *   
238 * @param npeID IxErrHdlAccNPEId [in] - NPE ID for NPEA, NPEB and NPEC.
239 * See @ref IxErrHdlAccNPEId
240 *
241 * @return IX_STATUS
242 * - IX_SUCCESS: Operation success
243 * - IX_FAIL : Invalid NPEID, Failure to Reset the NPE due
244               to time-out while waiting for the NPE to
245               reset and for the NPE FUSE Bit to turn off.
246 *
247 * <hr>
248 */
249PUBLIC IX_STATUS ixErrHdlAccNPEReset(IxErrHdlAccNPEId npeID);
250
251/**
252 * @ingroup IxErrHdlAcc
253 *
254 * @fn IX_STATUS ixErrHdlAccInit(void)
255 *
256 *
257 * @brief Initializes the ixErrHdlAcc component
258 *
259 *
260 * - Reentrant    - no
261 * - ISR Callable - no
262 *
263 * @pre The ixErrHdlAcc module should not already been
264 *      loaded or initialized.
265 *
266 * @return IX_STATUS
267 * - IX_SUCCESS: Module has initialized or already initialized.
268 * - IX_FAIL : Failure to create thread, create a semaphore
269 *             object & initializing of the module which is
270 *             already initialized.
271 * @sa ixErrHdlAccUnload
272 * <hr>
273 */
274PUBLIC IX_STATUS ixErrHdlAccInit(void);
275
276/**
277 * @ingroup IxErrHdlAcc
278 *
279 * @fn IX_STATUS ixErrHdlAccUnload(void)
280 *
281 *
282 * @brief Unloads the ixErrHdlAccModule, destroying the
283 *        semaphore object and killing all threads/tasks.
284 *
285 *
286 * - Reentrant    - no
287 * - ISR Callable - no
288 *
289 * @pre The ixErrHdlAcc module should have already
290 *      been intialized prior to calling this API.
291 *   
292 *
293 * @return IX_STATUS
294 * - IX_SUCCESS : Module has unloaded or already unloaded.
295 * - IX_FAIL : Failure to terminate thread, destroy a semaphore
296 *             objects and to de-allocate any allocated memory.
297 *             
298 * @sa ixErrHdlAccInit
299 * <hr>
300 */
301PUBLIC IX_STATUS ixErrHdlAccUnload(void);
302
303/**
304 * @ingroup IxErrHdlAcc
305 *
306 * @fn IX_STATUS ixErrHdlAccErrorHandlerGet (IxErrHdlAccErrorEventType event,IxErrHdlAccFuncHandler* handler)
307 *
308 *
309 * @brief API to get the event handler API to be called
310 * within the interrupt error ISR or task level to initiate
311 * a soft-error handling of the error.
312 *
313 * @note
314 *    For an NPE Error, the event handlers can be called
315 *    to reset the NPE irespective of whether there is
316 *    an NPE parity error or an AHB error. This API can
317 *    be used to restore the NPE in a need to need basis.
318 *
319 * - Reentrant    - no
320 * - ISR Callable - yes
321 *
322 * @pre The ixErrHdlAcc module should have already
323 *      been intialized prior to calling this API.
324 *   
325 * @param event IxErrHdlAccErrorEventType [in] An Event ID defined as:
326 * @ref IxErrHdlAccErrorEventType
327 *
328 * @param handler IxErrHdlAccFuncHandler* [in] A pointer to a Event Error
329 *            handler defined as @ref IxErrHdlAccFuncHandler
330 *
331 * @return IX_STATUS
332 * - IX_SUCCESS: Operation success
333 * - IX_FAIL : An uninitialized ixErrHdlAcc module or
334 *             a NULL pointer provided to the 2nd
335 *             parameter argument of the function or
336 *             an invalid Event ID (1st Parameter)
337 *
338 * <hr>
339 */
340PUBLIC IX_STATUS ixErrHdlAccErrorHandlerGet(IxErrHdlAccErrorEventType event, IxErrHdlAccFuncHandler* handler);
341
342/**
343 * @ingroup IxErrHdlAcc
344 *
345 * @fn IX_STATUS ixErrHdlAccStatusSet(UINT32 status)
346 *
347 *
348 * @brief Sets the current Error condition status results
349 *        that indicates if there was an error in handling
350 *        a soft-error.
351 * @warning
352 * This function  must be used only in conditions whereby,
353 * the client performs it’s own error handling in addition
354 * to the ones provided by the ixErrHdlAcc component which
355 * may result in recovery failure. This is particularly
356 * applicable for customized NPE firmware done by customers.
357 * The API then must be called to indicate an error in the
358 * hardware component impacted.
359 *
360 * @note
361 * Usage guide: This API can be used to set the Event Error WORD
362 * condition where, any bit N set in the status WORD (32bit) shall
363 * indicate an error. Currently only bit N = 0, 1, 2 & 3 is valid.
364 * @n An Example,   
365 *       @n This enables NPE A and NPE C Error handling.
366 *       @n ixErrHdlAccStatusSet(IX_ERRHDLACC_NPEA_ERROR_MASK_BIT
367 *                            |IX_ERRHDLACC_NPEC_ERROR_MASK_BIT);
368 *                 
369 *
370 * - Reentrant    - no
371 * - ISR Callable - yes
372 *
373 * @pre The ixErrHdlAcc module should have already
374 *      been intialized prior to calling this API.
375 *   
376 * @param status UINT32 [in] UINT32 (WORD)
377 *    to write the current Event Status condition WORD
378 *                                   
379 * @return IX_STATUS
380 * - IX_SUCCESS: Operation success
381 * - IX_FAIL : An uninitialized ixErrHdlAcc module
382 * @sa ixErrHdlAccStatusGet
383 * <hr>
384 */
385PUBLIC IX_STATUS ixErrHdlAccStatusSet(UINT32 status);
386
387/**
388 * @ingroup IxErrHdlAcc
389 *
390 * @fn IX_STATUS ixErrHdlAccStatusGet(UINT32* status)
391 *
392 *
393 * @brief Gets the current Error condition status results
394 *        that indicates if there was an error in handling
395 *        a soft-error.
396 * @note
397 * Usage guide:
398 *       This API can be used to get the Event Error WORD
399 *        condition where,
400 *       Any bit N set in the status WORD (32bit) shall
401 *       indicate an error.
402 *       Currently only bit N = 0, 1, 2 & 3 is valid.
403 *       
404 * @par Usage Example:   
405 *       This example gets the current status and checks
406 *       for NPE A Error.
407 *       @n ixErrHdlAccStatusGet(&status);
408 *       @n if(status&IX_ERRHDLACC_NPEA_ERROR_MASK_BIT)
409 *       @n {< NPE A Error> }
410 *
411 * - Reentrant    - no
412 * - ISR Callable - yes
413 *
414 * @pre The ixErrHdlAcc module should have already
415 *      been intialized prior to calling this API.
416 *   
417 * @param status UINT32 [in] Pointer to a UINT32 (WORD)
418 *    to write the current Event Status condition WORD
419 *                                   
420 *
421 * @return IX_STATUS
422 * - IX_SUCCESS: Operation success
423 * - IX_FAIL : An uninitialized ixErrHdlAcc module or
424 *             a NULL pointer provided to the 1st
425 *             parameter.
426 * @sa ixErrHdlAccStatusSet
427 * <hr>
428 */
429 PUBLIC IX_STATUS ixErrHdlAccStatusGet(UINT32* status);
430 
431
432
433/**
434 * @ingroup IxErrHdlAcc
435 *
436 * @fn void ixErrHdlAccStatisticsShow(void)
437 *
438 *
439 * @brief Displays the Debug/Measurement statistics
440 *        recorded by the module.
441 *       
442 *
443 *
444 * - Reentrant    - no
445 * - ISR Callable - no
446 *
447 *
448 * @return NONE
449 * @sa ixErrHdlAccStatisticsClear
450 * @sa ixErrHdlAccStatisticsGet
451 * <hr>
452 */
453PUBLIC void ixErrHdlAccStatisticsShow(void);
454
455/**
456 * @ingroup IxErrHdlAcc
457 *
458 * @fn IX_STATUS ixErrHdlAccStatisticsGet(IxErrHdlAccRecoveryStatistics* statistics)
459 *
460 *
461 * @brief API to retrieve the statistics recorded by
462 *        the module.
463 * @note
464 * See @ref IxErrHdlAccRecoveryStatistics for details
465 *
466 * - Reentrant    - no
467 * - ISR Callable - no
468 *
469 * @pre The ixErrHdlAcc module should have already
470 *      been intialized prior to calling this API.
471 *   
472 * @param statistics IxErrHdlAccRecoveryStatistics [in]
473 *
474 * @return IX_STATUS
475 * - IX_SUCCESS
476 * - IX_FAIL : An uninitialized ixErrHdlAcc module or
477 *             a NULL pointer provided to the 1st
478 *             parameter argument of the function.
479 * @sa ixErrHdlAccStatisticsClear
480 * @sa ixErrHdlAccStatisticsShow
481 * <hr>
482 */
483PUBLIC IX_STATUS ixErrHdlAccStatisticsGet(IxErrHdlAccRecoveryStatistics* statistics);
484
485/**
486 * @ingroup IxErrHdlAcc
487 *
488 * @fn void ixErrHdlAccStatisticsClear(void)
489 *
490 *
491 * @brief Resets and Clears the Debug/Measurement statistics
492 *        recorded by the module.
493 *       
494 *
495 *
496 * - Reentrant    - no
497 * - ISR Callable - no
498 *
499 *
500 * @return NONE
501 * @sa ixErrHdlAccStatisticsGet
502 * @sa ixErrHdlAccStatisticsShow
503 * <hr>
504 */
505PUBLIC void ixErrHdlAccStatisticsClear(void);
506
507 /**
508 * @ingroup IxErrHdlAcc
509 *
510 * @fn IX_STATUS ixErrHdlAccCallbackRegister(IxErrHdlAccRecoveryDoneCallback callback)
511 *
512 * @brief API to register a Completion done that is called after every completion of
513 * an error handling.   
514 *
515 *
516 * - Reentrant    - no
517 * - ISR Callable - no
518 *
519 * @pre The ixErrHdlAcc module should have already
520 *      been intialized prior to calling this API.
521 *   
522 * @param callback IxErrHdlAccRecoveryDoneCallback [in] Call-back function to be called by the module
523 *        upon completion of a recovery task. See @ref IxErrHdlAccRecoveryDoneCallback
524 *
525 * @return IX_STATUS
526 * - IX_SUCCESS: Operation success
527 * - IX_FAIL : An uninitialized ixErrHdlAcc module or
528 *             a NULL pointer provided to the 1st
529 *             parameter argument of the function.
530 *
531 * <hr>
532 */
533PUBLIC IX_STATUS ixErrHdlAccCallbackRegister(IxErrHdlAccRecoveryDoneCallback callback);
534
535#endif
536/**
537 *@}
538 */
Note: See TracBrowser for help on using the repository browser.