1 /* Copyright (c) 2008-2011 Freescale Semiconductor, Inc.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above copyright
9 * notice, this list of conditions and the following disclaimer in the
10 * documentation and/or other materials provided with the distribution.
11 * * Neither the name of Freescale Semiconductor nor the
12 * names of its contributors may be used to endorse or promote products
13 * derived from this software without specific prior written permission.
16 * ALTERNATIVELY, this software may be distributed under the terms of the
17 * GNU General Public License ("GPL") as published by the Free Software
18 * Foundation, either version 2 of that License or (at your option) any
21 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
22 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
25 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 @Description Error definitions.
37 *//***************************************************************************/
46 /**************************************************************************//**
47 @Group gen_id General Drivers Utilities
49 @Description External routines.
52 *//***************************************************************************/
54 /**************************************************************************//**
55 @Group gen_error_id Errors, Events and Debug
57 @Description External routines.
60 *//***************************************************************************/
62 /******************************************************************************
63 The scheme below provides the bits description for error codes:
65 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
66 | Reserved (should be zero) | Module ID |
68 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
70 ******************************************************************************/
72 #define ERROR_CODE(_err) ((((uint32_t)_err) & 0x0000FFFF) | __ERR_MODULE__)
74 #define GET_ERROR_TYPE(_errcode) ((_errcode) & 0x0000FFFF)
75 /**< Extract module code from error code (#t_Error) */
77 #define GET_ERROR_MODULE(_errcode) ((_errcode) & 0x00FF0000)
78 /**< Extract error type (#e_ErrorType) from
79 error code (#t_Error) */
82 /**************************************************************************//**
83 @Description Error Type Enumeration
84 *//***************************************************************************/
85 typedef enum e_ErrorType /* Comments / Associated Message Strings */
86 { /* ------------------------------------------------------------ */
87 E_OK = 0 /* Never use "RETURN_ERROR" with E_OK; Use "return E_OK;" */
89 /* Invalid Function Calls */
90 ,E_INVALID_STATE /**< The operation is not allowed in current module state. */
92 ,E_INVALID_OPERATION /**< The operation/command is invalid (unrecognized). */
94 ,E_NOT_SUPPORTED /**< The function is not supported or not implemented. */
96 ,E_NO_DEVICE /**< The associated device is not initialized. */
99 /* Invalid Parameters */
100 ,E_INVALID_HANDLE /**< Invalid handle of module or object. */
101 /* String: none, unless the function takes in more than one
102 handle (in this case add the handle description) */
103 ,E_INVALID_ID /**< Invalid module ID (usually enumeration or index). */
104 /* String: none, unless the function takes in more than one
105 ID (in this case add the ID description) */
106 ,E_NULL_POINTER /**< Unexpected NULL pointer. */
107 /* String: pointer description. */
108 ,E_INVALID_VALUE /**< Invalid value. */
109 /* Use for non-enumeration parameters, and
110 only when other error types are not suitable.
111 String: parameter description + "(should be <attribute>)",
112 e.g: "Maximum Rx buffer length (should be divisible by 8)",
113 "Channel number (should be even)". */
114 ,E_INVALID_SELECTION /**< Invalid selection or mode. */
115 /* Use for enumeration values, only when other error types
117 String: parameter description. */
118 ,E_INVALID_COMM_MODE /**< Invalid communication mode. */
119 /* String: none, unless the function takes in more than one
120 communication mode indications (in this case add
121 parameter description). */
122 ,E_INVALID_BYTE_ORDER /**< Invalid byte order. */
123 /* String: none, unless the function takes in more than one
124 byte order indications (in this case add parameter
126 ,E_INVALID_MEMORY_TYPE /**< Invalid memory type. */
127 /* String: none, unless the function takes in more than one
128 memory types (in this case add memory description,
129 e.g: "Data memory", "Buffer descriptors memory"). */
130 ,E_INVALID_INTR_QUEUE /**< Invalid interrupt queue. */
131 /* String: none, unless the function takes in more than one
132 interrupt queues (in this case add queue description,
133 e.g: "Rx interrupt queue", "Tx interrupt queue"). */
134 ,E_INVALID_PRIORITY /**< Invalid priority. */
135 /* String: none, unless the function takes in more than one
136 priority (in this case add priority description). */
137 ,E_INVALID_CLOCK /**< Invalid clock. */
138 /* String: none, unless the function takes in more than one
139 clocks (in this case add clock description,
140 e.g: "Rx clock", "Tx clock"). */
141 ,E_INVALID_RATE /**< Invalid rate value. */
142 /* String: none, unless the function takes in more than one
143 rate values (in this case add rate description). */
144 ,E_INVALID_ADDRESS /**< Invalid address. */
145 /* String: description of the specific violation. */
146 ,E_INVALID_BUS /**< Invalid bus type. */
147 /* String: none, unless the function takes in more than one
148 bus parameters (in this case add bus description). */
149 ,E_BUS_CONFLICT /**< Bus (or memory) type conflicts with another setting. */
150 /* String: description of the conflicting buses/memories. */
151 ,E_CONFLICT /**< Some setting conflicts with another setting. */
152 /* String: description of the conflicting settings. */
153 ,E_NOT_ALIGNED /**< Non-aligned address. */
154 /* String: parameter description + "(should be %d-bytes aligned)",
155 e.g: "Rx data buffer (should be 32-bytes aligned)". */
156 ,E_NOT_IN_RANGE /**< Parameter value is out of range. */
157 /* Don't use this error for enumeration parameters.
158 String: parameter description + "(should be %d-%d)",
159 e.g: "Number of pad characters (should be 0-15)". */
161 /* Frame/Buffer Errors */
162 ,E_INVALID_FRAME /**< Invalid frame object (NULL handle or missing buffers). */
164 ,E_EMPTY_FRAME /**< Frame object is empty (has no buffers). */
166 ,E_EMPTY_BUFFER /**< Buffer object is empty (no data, or zero data length). */
169 /* Resource Errors */
170 ,E_NO_MEMORY /**< External memory allocation failed. */
171 /* String: description of item for which allocation failed. */
172 ,E_NOT_FOUND /**< Requested resource or item was not found. */
173 /* Use only when the resource/item is uniquely identified.
174 String: none, unless the operation is not the main goal
175 of the function (in this case add item description). */
176 ,E_NOT_AVAILABLE /**< Resource is unavailable. */
177 /* String: none, unless the operation is not the main goal
178 of the function (in this case add resource description). */
179 ,E_ALREADY_EXISTS /**< Requested resource or item already exists. */
180 /* Use when resource duplication or sharing are not allowed.
181 String: none, unless the operation is not the main goal
182 of the function (in this case add item description). */
183 ,E_FULL /**< Resource is full. */
184 /* String: none, unless the operation is not the main goal
185 of the function (in this case add resource description). */
186 ,E_EMPTY /**< Resource is empty. */
187 /* String: none, unless the operation is not the main goal
188 of the function (in this case add resource description). */
189 ,E_BUSY /**< Resource or module is busy. */
190 /* String: none, unless the operation is not the main goal
191 of the function (in this case add resource description). */
192 ,E_ALREADY_FREE /**< Specified resource or item is already free or deleted. */
193 /* String: none, unless the operation is not the main goal
194 of the function (in this case add item description). */
196 /* Read/Write Access Errors */
197 ,E_READ_FAILED /**< Read access failed on memory/device. */
198 /* String: none, or device name. */
199 ,E_WRITE_FAILED /**< Write access failed on memory/device. */
200 /* String: none, or device name. */
202 /* Send/Receive Failures */
203 ,E_SEND_FAILED /**< Send operation failed on device. */
204 /* String: none, or device name. */
205 ,E_RECEIVE_FAILED /**< Receive operation failed on device. */
206 /* String: none, or device name. */
208 /* Operation time-out */
209 ,E_TIMEOUT /**< The operation timed out. */
212 ,E_DUMMY_LAST /* NEVER USED */
217 /**************************************************************************//**
218 @Description Event Type Enumeration
219 *//***************************************************************************/
220 typedef enum e_Event /* Comments / Associated Flags and Message Strings */
221 { /* ------------------------------------------------------------ */
222 EV_NO_EVENT = 0 /**< No event; Never used. */
224 ,EV_RX_DISCARD /**< Received packet discarded (by the driver, and only for
226 Flags: error flags in case of error, zero otherwise. */
227 /* String: reason for discard, e.g: "Error in frame",
228 "Disordered frame", "Incomplete frame", "No frame object". */
229 ,EV_RX_ERROR /**< Receive error (by hardware/firmware);
230 Flags: usually status flags from the buffer descriptor. */
232 ,EV_TX_ERROR /**< Transmit error (by hardware/firmware);
233 Flags: usually status flags from the buffer descriptor. */
235 ,EV_NO_BUFFERS /**< System ran out of buffer objects;
238 ,EV_NO_MB_FRAMES /**< System ran out of multi-buffer frame objects;
241 ,EV_NO_SB_FRAMES /**< System ran out of single-buffer frame objects;
244 ,EV_TX_QUEUE_FULL /**< Transmit queue is full;
247 ,EV_RX_QUEUE_FULL /**< Receive queue is full;
250 ,EV_INTR_QUEUE_FULL /**< Interrupt queue overflow;
253 ,EV_NO_DATA_BUFFER /**< Data buffer allocation (from higher layer) failed;
256 ,EV_OBJ_POOL_EMPTY /**< Objects pool is empty;
258 /* String: object description (name). */
259 ,EV_BUS_ERROR /**< Illegal access on bus;
260 Flags: the address (if available) or bus identifier */
261 /* String: bus/address/module description. */
262 ,EV_PTP_TXTS_QUEUE_FULL /**< PTP Tx timestamps queue is full;
265 ,EV_PTP_RXTS_QUEUE_FULL /**< PTP Rx timestamps queue is full;
273 /**************************************************************************//**
274 @Collection Debug Levels for Errors and Events
276 The level description refers to errors only.
277 For events, classification is done by the user.
279 The TRACE, INFO and WARNING levels are allowed only when using
280 the DBG macro, and are not allowed when using the error macros
281 (RETURN_ERROR or REPORT_ERROR).
283 *//***************************************************************************/
284 #define REPORT_LEVEL_CRITICAL 1 /**< Crasher: Incorrect flow, NULL pointers/handles. */
285 #define REPORT_LEVEL_MAJOR 2 /**< Cannot proceed: Invalid operation, parameters or
287 #define REPORT_LEVEL_MINOR 3 /**< Recoverable problem: a repeating call with the same
288 parameters may be successful. */
289 #define REPORT_LEVEL_WARNING 4 /**< Something is not exactly right, yet it is not an error. */
290 #define REPORT_LEVEL_INFO 5 /**< Messages which may be of interest to user/programmer. */
291 #define REPORT_LEVEL_TRACE 6 /**< Program flow messages. */
293 #define EVENT_DISABLED 0xFF /**< Disabled event (not reported at all) */
301 #ifndef DEBUG_GLOBAL_LEVEL
302 #define DEBUG_GLOBAL_LEVEL REPORT_LEVEL_WARNING
303 #endif /* DEBUG_GLOBAL_LEVEL */
305 #ifndef ERROR_GLOBAL_LEVEL
306 #define ERROR_GLOBAL_LEVEL DEBUG_GLOBAL_LEVEL
307 #endif /* ERROR_GLOBAL_LEVEL */
309 #ifndef EVENT_GLOBAL_LEVEL
310 #define EVENT_GLOBAL_LEVEL REPORT_LEVEL_MINOR
311 #endif /* EVENT_GLOBAL_LEVEL */
313 #ifdef EVENT_LOCAL_LEVEL
314 #define EVENT_DYNAMIC_LEVEL EVENT_LOCAL_LEVEL
316 #define EVENT_DYNAMIC_LEVEL EVENT_GLOBAL_LEVEL
317 #endif /* EVENT_LOCAL_LEVEL */
320 #ifndef DEBUG_DYNAMIC_LEVEL
321 #define DEBUG_USING_STATIC_LEVEL
323 #ifdef DEBUG_STATIC_LEVEL
324 #define DEBUG_DYNAMIC_LEVEL DEBUG_STATIC_LEVEL
326 #define DEBUG_DYNAMIC_LEVEL DEBUG_GLOBAL_LEVEL
327 #endif /* DEBUG_STATIC_LEVEL */
329 #else /* DEBUG_DYNAMIC_LEVEL */
330 #ifdef DEBUG_STATIC_LEVEL
331 #error "Please use either DEBUG_STATIC_LEVEL or DEBUG_DYNAMIC_LEVEL (not both)"
333 int DEBUG_DYNAMIC_LEVEL = DEBUG_GLOBAL_LEVEL;
334 #endif /* DEBUG_STATIC_LEVEL */
335 #endif /* !DEBUG_DYNAMIC_LEVEL */
338 #ifndef ERROR_DYNAMIC_LEVEL
340 #ifdef ERROR_STATIC_LEVEL
341 #define ERROR_DYNAMIC_LEVEL ERROR_STATIC_LEVEL
343 #define ERROR_DYNAMIC_LEVEL ERROR_GLOBAL_LEVEL
344 #endif /* ERROR_STATIC_LEVEL */
346 #else /* ERROR_DYNAMIC_LEVEL */
347 #ifdef ERROR_STATIC_LEVEL
348 #error "Please use either ERROR_STATIC_LEVEL or ERROR_DYNAMIC_LEVEL (not both)"
350 int ERROR_DYNAMIC_LEVEL = ERROR_GLOBAL_LEVEL;
351 #endif /* ERROR_STATIC_LEVEL */
352 #endif /* !ERROR_DYNAMIC_LEVEL */
354 #define PRINT_FORMAT "[CPU%02d, %s:%d %s]"
355 #define PRINT_FMT_PARAMS CORE_GetId(), __FILE__, __LINE__, __FUNCTION__
356 #define _ERR_STRING(err) #err
357 #define ERR_STRING(err) _ERR_STRING(err)
359 #if (!(defined(DEBUG_ERRORS)) || (DEBUG_ERRORS == 0))
360 /* No debug/error/event messages at all */
361 #define DBG(_level, _vmsg)
363 #define REPORT_ERROR(_level, _err, _vmsg)
365 #define RETURN_ERROR(_level, _err, _vmsg) \
366 return ERROR_CODE(_err)
368 #if (REPORT_EVENTS > 0)
370 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) \
372 if (_ev##_LEVEL <= EVENT_DYNAMIC_LEVEL) { \
373 XX_EventById((uint32_t)(_ev), (t_Handle)(_appId), (uint16_t)(_flg), NO_MSG); \
379 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg)
381 #endif /* (REPORT_EVENTS > 0) */
384 #else /* DEBUG_ERRORS > 0 */
386 extern const char *dbgLevelStrings[];
387 extern const char *errTypeStrings[];
388 extern const char *moduleStrings[];
389 #if (REPORT_EVENTS > 0)
390 extern const char *eventStrings[];
391 #endif /* (REPORT_EVENTS > 0) */
394 #if ((defined(DEBUG_USING_STATIC_LEVEL)) && (DEBUG_DYNAMIC_LEVEL < REPORT_LEVEL_WARNING))
395 /* No need for DBG macro - debug level is higher anyway */
396 #define DBG(_level, _vmsg)
398 #define DBG(_level, _vmsg) \
400 if (REPORT_LEVEL_##_level <= DEBUG_DYNAMIC_LEVEL) { \
401 XX_Print("> %s (%s) " PRINT_FORMAT ": ", \
402 dbgLevelStrings[REPORT_LEVEL_##_level - 1], \
403 ERR_STRING(__ERR_MODULE__), \
409 #endif /* (defined(DEBUG_USING_STATIC_LEVEL) && (DEBUG_DYNAMIC_LEVEL < WARNING)) */
412 #define REPORT_ERROR(_level, _err, _vmsg) \
414 if (REPORT_LEVEL_##_level <= ERROR_DYNAMIC_LEVEL) { \
415 XX_Print("! %s %s Error " PRINT_FORMAT ": %s; ", \
416 dbgLevelStrings[REPORT_LEVEL_##_level - 1], \
417 ERR_STRING(__ERR_MODULE__), \
419 errTypeStrings[(GET_ERROR_TYPE(_err) - E_OK - 1)]); \
426 #define RETURN_ERROR(_level, _err, _vmsg) \
428 REPORT_ERROR(_level, (_err), _vmsg); \
429 return ERROR_CODE(_err); \
433 #if (REPORT_EVENTS > 0)
435 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) \
437 if (_ev##_LEVEL <= EVENT_DYNAMIC_LEVEL) { \
438 XX_Print("~ %s %s Event " PRINT_FORMAT ": %s (flags: 0x%04x); ", \
439 dbgLevelStrings[_ev##_LEVEL - 1], \
440 ERR_STRING(__ERR_MODULE__), \
442 eventStrings[((_ev) - EV_NO_EVENT - 1)], \
446 XX_EventById((uint32_t)(_ev), (t_Handle)(_appId), (uint16_t)(_flg), NO_MSG); \
450 #else /* not REPORT_EVENTS */
452 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg)
454 #endif /* (REPORT_EVENTS > 0) */
456 #endif /* (DEBUG_ERRORS > 0) */
459 /**************************************************************************//**
460 @Function ASSERT_COND
462 @Description Assertion macro.
464 @Param[in] _cond - The condition being checked, in positive form;
465 Failure of the condition triggers the assert.
466 *//***************************************************************************/
467 #ifdef DISABLE_ASSERTIONS
468 #define ASSERT_COND(_cond)
470 #define ASSERT_COND(_cond) \
473 XX_Print("*** ASSERT_COND failed " PRINT_FORMAT "\r\n", \
478 #endif /* DISABLE_ASSERTIONS */
481 #ifdef DISABLE_INIT_PARAMETERS_CHECK
483 #define CHECK_INIT_PARAMETERS(handle, f_check)
484 #define CHECK_INIT_PARAMETERS_RETURN_VALUE(handle, f_check, retval)
488 #define CHECK_INIT_PARAMETERS(handle, f_check) \
490 t_Error err = f_check(handle); \
492 RETURN_ERROR(MAJOR, err, NO_MSG); \
496 #define CHECK_INIT_PARAMETERS_RETURN_VALUE(handle, f_check, retval) \
498 t_Error err = f_check(handle); \
500 REPORT_ERROR(MAJOR, err, NO_MSG); \
505 #endif /* DISABLE_INIT_PARAMETERS_CHECK */
507 #ifdef DISABLE_SANITY_CHECKS
509 #define SANITY_CHECK_RETURN_ERROR(_cond, _err)
510 #define SANITY_CHECK_RETURN_VALUE(_cond, _err, retval)
511 #define SANITY_CHECK_RETURN(_cond, _err)
512 #define SANITY_CHECK_EXIT(_cond, _err)
514 #else /* DISABLE_SANITY_CHECKS */
516 #define SANITY_CHECK_RETURN_ERROR(_cond, _err) \
519 RETURN_ERROR(CRITICAL, (_err), NO_MSG); \
523 #define SANITY_CHECK_RETURN_VALUE(_cond, _err, retval) \
526 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \
531 #define SANITY_CHECK_RETURN(_cond, _err) \
534 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \
539 #define SANITY_CHECK_EXIT(_cond, _err) \
542 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \
547 #endif /* DISABLE_SANITY_CHECKS */
549 /** @} */ /* end of Debug/error Utils group */
551 /** @} */ /* end of General Utils group */
553 #endif /* __ERROR_EXT_H */