1 /* Copyright (c) 2008-2012 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.
34 /**************************************************************************//**
37 @Description Error definitions.
38 *//***************************************************************************/
43 #if defined(NCSW_FREEBSD)
44 #include <sys/param.h>
45 #include <sys/errno.h>
56 /**************************************************************************//**
57 @Group gen_id General Drivers Utilities
59 @Description External routines.
62 *//***************************************************************************/
64 /**************************************************************************//**
65 @Group gen_error_id Errors, Events and Debug
67 @Description External routines.
70 *//***************************************************************************/
72 /******************************************************************************
73 The scheme below provides the bits description for error codes:
75 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
76 | Reserved (should be zero) | Module ID |
78 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
80 ******************************************************************************/
82 #define ERROR_CODE(_err) ((((uint32_t)_err) & 0x0000FFFF) | __ERR_MODULE__)
84 #define GET_ERROR_TYPE(_errcode) ((_errcode) & 0x0000FFFF)
85 /**< Extract module code from error code (#t_Error) */
87 #define GET_ERROR_MODULE(_errcode) ((_errcode) & 0x00FF0000)
88 /**< Extract error type (#e_ErrorType) from
89 error code (#t_Error) */
92 /**************************************************************************//**
93 @Description Error Type Enumeration
94 *//***************************************************************************/
95 typedef enum e_ErrorType /* Comments / Associated Message Strings */
96 { /* ------------------------------------------------------------ */
97 E_OK = 0 /* Never use "RETURN_ERROR" with E_OK; Use "return E_OK;" */
98 ,E_WRITE_FAILED = EIO /**< Write access failed on memory/device. */
99 /* String: none, or device name. */
100 ,E_NO_DEVICE = ENXIO /**< The associated device is not initialized. */
102 ,E_NOT_AVAILABLE = EAGAIN
103 /**< Resource is unavailable. */
104 /* String: none, unless the operation is not the main goal
105 of the function (in this case add resource description). */
106 ,E_NO_MEMORY = ENOMEM /**< External memory allocation failed. */
107 /* String: description of item for which allocation failed. */
108 ,E_INVALID_ADDRESS = EFAULT
109 /**< Invalid address. */
110 /* String: description of the specific violation. */
111 ,E_BUSY = EBUSY /**< Resource or module is busy. */
112 /* String: none, unless the operation is not the main goal
113 of the function (in this case add resource description). */
114 ,E_ALREADY_EXISTS = EEXIST
115 /**< Requested resource or item already exists. */
116 /* Use when resource duplication or sharing are not allowed.
117 String: none, unless the operation is not the main goal
118 of the function (in this case add item description). */
119 ,E_INVALID_OPERATION = ENODEV
120 /**< The operation/command is invalid (unrecognized). */
122 ,E_INVALID_VALUE = EDOM /**< Invalid value. */
123 /* Use for non-enumeration parameters, and
124 only when other error types are not suitable.
125 String: parameter description + "(should be <attribute>)",
126 e.g: "Maximum Rx buffer length (should be divisible by 8)",
127 "Channel number (should be even)". */
128 ,E_NOT_IN_RANGE = ERANGE/**< Parameter value is out of range. */
129 /* Don't use this error for enumeration parameters.
130 String: parameter description + "(should be %d-%d)",
131 e.g: "Number of pad characters (should be 0-15)". */
132 ,E_NOT_SUPPORTED = ENOSYS
133 /**< The function is not supported or not implemented. */
135 ,E_INVALID_STATE /**< The operation is not allowed in current module state. */
137 ,E_INVALID_HANDLE /**< Invalid handle of module or object. */
138 /* String: none, unless the function takes in more than one
139 handle (in this case add the handle description) */
140 ,E_INVALID_ID /**< Invalid module ID (usually enumeration or index). */
141 /* String: none, unless the function takes in more than one
142 ID (in this case add the ID description) */
143 ,E_NULL_POINTER /**< Unexpected NULL pointer. */
144 /* String: pointer description. */
145 ,E_INVALID_SELECTION /**< Invalid selection or mode. */
146 /* Use for enumeration values, only when other error types
148 String: parameter description. */
149 ,E_INVALID_COMM_MODE /**< Invalid communication mode. */
150 /* String: none, unless the function takes in more than one
151 communication mode indications (in this case add
152 parameter description). */
153 ,E_INVALID_MEMORY_TYPE /**< Invalid memory type. */
154 /* String: none, unless the function takes in more than one
155 memory types (in this case add memory description,
156 e.g: "Data memory", "Buffer descriptors memory"). */
157 ,E_INVALID_CLOCK /**< Invalid clock. */
158 /* String: none, unless the function takes in more than one
159 clocks (in this case add clock description,
160 e.g: "Rx clock", "Tx clock"). */
161 ,E_CONFLICT /**< Some setting conflicts with another setting. */
162 /* String: description of the conflicting settings. */
163 ,E_NOT_ALIGNED /**< Non-aligned address. */
164 /* String: parameter description + "(should be %d-bytes aligned)",
165 e.g: "Rx data buffer (should be 32-bytes aligned)". */
166 ,E_NOT_FOUND /**< Requested resource or item was not found. */
167 /* Use only when the resource/item is uniquely identified.
168 String: none, unless the operation is not the main goal
169 of the function (in this case add item description). */
170 ,E_FULL /**< Resource is full. */
171 /* String: none, unless the operation is not the main goal
172 of the function (in this case add resource description). */
173 ,E_EMPTY /**< Resource is empty. */
174 /* String: none, unless the operation is not the main goal
175 of the function (in this case add resource description). */
176 ,E_ALREADY_FREE /**< Specified resource or item is already free or deleted. */
177 /* String: none, unless the operation is not the main goal
178 of the function (in this case add item description). */
179 ,E_READ_FAILED /**< Read access failed on memory/device. */
180 /* String: none, or device name. */
181 ,E_INVALID_FRAME /**< Invalid frame object (NULL handle or missing buffers). */
183 ,E_SEND_FAILED /**< Send operation failed on device. */
184 /* String: none, or device name. */
185 ,E_RECEIVE_FAILED /**< Receive operation failed on device. */
186 /* String: none, or device name. */
187 ,E_TIMEOUT/* = ETIMEDOUT*/ /**< The operation timed out. */
190 ,E_DUMMY_LAST /* NEVER USED */
194 /**************************************************************************//**
195 @Description Event Type Enumeration
196 *//***************************************************************************/
197 typedef enum e_Event /* Comments / Associated Flags and Message Strings */
198 { /* ------------------------------------------------------------ */
199 EV_NO_EVENT = 0 /**< No event; Never used. */
201 ,EV_RX_DISCARD /**< Received packet discarded (by the driver, and only for
203 Flags: error flags in case of error, zero otherwise. */
204 /* String: reason for discard, e.g: "Error in frame",
205 "Disordered frame", "Incomplete frame", "No frame object". */
206 ,EV_RX_ERROR /**< Receive error (by hardware/firmware);
207 Flags: usually status flags from the buffer descriptor. */
209 ,EV_TX_ERROR /**< Transmit error (by hardware/firmware);
210 Flags: usually status flags from the buffer descriptor. */
212 ,EV_NO_BUFFERS /**< System ran out of buffer objects;
215 ,EV_NO_MB_FRAMES /**< System ran out of multi-buffer frame objects;
218 ,EV_NO_SB_FRAMES /**< System ran out of single-buffer frame objects;
221 ,EV_TX_QUEUE_FULL /**< Transmit queue is full;
224 ,EV_RX_QUEUE_FULL /**< Receive queue is full;
227 ,EV_INTR_QUEUE_FULL /**< Interrupt queue overflow;
230 ,EV_NO_DATA_BUFFER /**< Data buffer allocation (from higher layer) failed;
233 ,EV_OBJ_POOL_EMPTY /**< Objects pool is empty;
235 /* String: object description (name). */
236 ,EV_BUS_ERROR /**< Illegal access on bus;
237 Flags: the address (if available) or bus identifier */
238 /* String: bus/address/module description. */
239 ,EV_PTP_TXTS_QUEUE_FULL /**< PTP Tx timestamps queue is full;
242 ,EV_PTP_RXTS_QUEUE_FULL /**< PTP Rx timestamps queue is full;
250 /**************************************************************************//**
251 @Collection Debug Levels for Errors and Events
253 The level description refers to errors only.
254 For events, classification is done by the user.
256 The TRACE, INFO and WARNING levels are allowed only when using
257 the DBG macro, and are not allowed when using the error macros
258 (RETURN_ERROR or REPORT_ERROR).
260 *//***************************************************************************/
261 #define REPORT_LEVEL_CRITICAL 1 /**< Crasher: Incorrect flow, NULL pointers/handles. */
262 #define REPORT_LEVEL_MAJOR 2 /**< Cannot proceed: Invalid operation, parameters or
264 #define REPORT_LEVEL_MINOR 3 /**< Recoverable problem: a repeating call with the same
265 parameters may be successful. */
266 #define REPORT_LEVEL_WARNING 4 /**< Something is not exactly right, yet it is not an error. */
267 #define REPORT_LEVEL_INFO 5 /**< Messages which may be of interest to user/programmer. */
268 #define REPORT_LEVEL_TRACE 6 /**< Program flow messages. */
270 #define EVENT_DISABLED 0xFF /**< Disabled event (not reported at all) */
278 #ifndef DEBUG_GLOBAL_LEVEL
279 #define DEBUG_GLOBAL_LEVEL REPORT_LEVEL_WARNING
280 #endif /* DEBUG_GLOBAL_LEVEL */
282 #ifndef ERROR_GLOBAL_LEVEL
283 #define ERROR_GLOBAL_LEVEL DEBUG_GLOBAL_LEVEL
284 #endif /* ERROR_GLOBAL_LEVEL */
286 #ifndef EVENT_GLOBAL_LEVEL
287 #define EVENT_GLOBAL_LEVEL REPORT_LEVEL_MINOR
288 #endif /* EVENT_GLOBAL_LEVEL */
290 #ifdef EVENT_LOCAL_LEVEL
291 #define EVENT_DYNAMIC_LEVEL EVENT_LOCAL_LEVEL
293 #define EVENT_DYNAMIC_LEVEL EVENT_GLOBAL_LEVEL
294 #endif /* EVENT_LOCAL_LEVEL */
297 #ifndef DEBUG_DYNAMIC_LEVEL
298 #define DEBUG_USING_STATIC_LEVEL
300 #ifdef DEBUG_STATIC_LEVEL
301 #define DEBUG_DYNAMIC_LEVEL DEBUG_STATIC_LEVEL
303 #define DEBUG_DYNAMIC_LEVEL DEBUG_GLOBAL_LEVEL
304 #endif /* DEBUG_STATIC_LEVEL */
306 #else /* DEBUG_DYNAMIC_LEVEL */
307 #ifdef DEBUG_STATIC_LEVEL
308 #error "Please use either DEBUG_STATIC_LEVEL or DEBUG_DYNAMIC_LEVEL (not both)"
310 int DEBUG_DYNAMIC_LEVEL = DEBUG_GLOBAL_LEVEL;
311 #endif /* DEBUG_STATIC_LEVEL */
312 #endif /* !DEBUG_DYNAMIC_LEVEL */
315 #ifndef ERROR_DYNAMIC_LEVEL
317 #ifdef ERROR_STATIC_LEVEL
318 #define ERROR_DYNAMIC_LEVEL ERROR_STATIC_LEVEL
320 #define ERROR_DYNAMIC_LEVEL ERROR_GLOBAL_LEVEL
321 #endif /* ERROR_STATIC_LEVEL */
323 #else /* ERROR_DYNAMIC_LEVEL */
324 #ifdef ERROR_STATIC_LEVEL
325 #error "Please use either ERROR_STATIC_LEVEL or ERROR_DYNAMIC_LEVEL (not both)"
327 int ERROR_DYNAMIC_LEVEL = ERROR_GLOBAL_LEVEL;
328 #endif /* ERROR_STATIC_LEVEL */
329 #endif /* !ERROR_DYNAMIC_LEVEL */
331 #define PRINT_FORMAT "[CPU%02d, %s:%d %s]"
332 #define PRINT_FMT_PARAMS PCPU_GET(cpuid), __FILE__, __LINE__, __FUNCTION__
334 #if (!(defined(DEBUG_ERRORS)) || (DEBUG_ERRORS == 0))
335 /* No debug/error/event messages at all */
336 #define DBG(_level, _vmsg)
338 #define REPORT_ERROR(_level, _err, _vmsg)
340 #define RETURN_ERROR(_level, _err, _vmsg) \
341 return ERROR_CODE(_err)
343 #if (REPORT_EVENTS > 0)
345 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) \
347 if (_ev##_LEVEL <= EVENT_DYNAMIC_LEVEL) { \
348 XX_EventById((uint32_t)(_ev), (t_Handle)(_appId), (uint16_t)(_flg), NO_MSG); \
354 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg)
356 #endif /* (REPORT_EVENTS > 0) */
359 #else /* DEBUG_ERRORS > 0 */
361 extern const char *dbgLevelStrings[];
362 #if (REPORT_EVENTS > 0)
363 extern const char *eventStrings[];
364 #endif /* (REPORT_EVENTS > 0) */
366 char * ErrTypeStrings (e_ErrorType err);
369 #if ((defined(DEBUG_USING_STATIC_LEVEL)) && (DEBUG_DYNAMIC_LEVEL < REPORT_LEVEL_WARNING))
370 /* No need for DBG macro - debug level is higher anyway */
371 #define DBG(_level, _vmsg)
373 #define DBG(_level, _vmsg) \
375 if (REPORT_LEVEL_##_level <= DEBUG_DYNAMIC_LEVEL) { \
376 XX_Print("> %s (%s) " PRINT_FORMAT ": ", \
377 dbgLevelStrings[REPORT_LEVEL_##_level - 1], \
378 __STRING(__ERR_MODULE__), \
384 #endif /* (defined(DEBUG_USING_STATIC_LEVEL) && (DEBUG_DYNAMIC_LEVEL < WARNING)) */
387 #define REPORT_ERROR(_level, _err, _vmsg) \
389 if (REPORT_LEVEL_##_level <= ERROR_DYNAMIC_LEVEL) { \
390 XX_Print("! %s %s Error " PRINT_FORMAT ": %s; ", \
391 dbgLevelStrings[REPORT_LEVEL_##_level - 1], \
392 __STRING(__ERR_MODULE__), \
394 ErrTypeStrings((e_ErrorType)GET_ERROR_TYPE(_err))); \
401 #define RETURN_ERROR(_level, _err, _vmsg) \
403 REPORT_ERROR(_level, (_err), _vmsg); \
404 return ERROR_CODE(_err); \
408 #if (REPORT_EVENTS > 0)
410 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) \
412 if (_ev##_LEVEL <= EVENT_DYNAMIC_LEVEL) { \
413 XX_Print("~ %s %s Event " PRINT_FORMAT ": %s (flags: 0x%04x); ", \
414 dbgLevelStrings[_ev##_LEVEL - 1], \
415 __STRING(__ERR_MODULE__), \
417 eventStrings[((_ev) - EV_NO_EVENT - 1)], \
421 XX_EventById((uint32_t)(_ev), (t_Handle)(_appId), (uint16_t)(_flg), NO_MSG); \
425 #else /* not REPORT_EVENTS */
427 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg)
429 #endif /* (REPORT_EVENTS > 0) */
431 #endif /* (DEBUG_ERRORS > 0) */
434 /**************************************************************************//**
435 @Function ASSERT_COND
437 @Description Assertion macro.
439 @Param[in] _cond - The condition being checked, in positive form;
440 Failure of the condition triggers the assert.
441 *//***************************************************************************/
442 #ifdef DISABLE_ASSERTIONS
443 #define ASSERT_COND(_cond)
445 #define ASSERT_COND(_cond) \
448 XX_Print("*** ASSERT_COND failed " PRINT_FORMAT "\r\n", \
453 #endif /* DISABLE_ASSERTIONS */
456 #ifdef DISABLE_INIT_PARAMETERS_CHECK
458 #define CHECK_INIT_PARAMETERS(handle, f_check)
459 #define CHECK_INIT_PARAMETERS_RETURN_VALUE(handle, f_check, retval)
463 #define CHECK_INIT_PARAMETERS(handle, f_check) \
465 t_Error err = f_check(handle); \
467 RETURN_ERROR(MAJOR, err, NO_MSG); \
471 #define CHECK_INIT_PARAMETERS_RETURN_VALUE(handle, f_check, retval) \
473 t_Error err = f_check(handle); \
475 REPORT_ERROR(MAJOR, err, NO_MSG); \
480 #endif /* DISABLE_INIT_PARAMETERS_CHECK */
482 #ifdef DISABLE_SANITY_CHECKS
484 #define SANITY_CHECK_RETURN_ERROR(_cond, _err)
485 #define SANITY_CHECK_RETURN_VALUE(_cond, _err, retval)
486 #define SANITY_CHECK_RETURN(_cond, _err)
487 #define SANITY_CHECK_EXIT(_cond, _err)
489 #else /* DISABLE_SANITY_CHECKS */
491 #define SANITY_CHECK_RETURN_ERROR(_cond, _err) \
494 RETURN_ERROR(CRITICAL, (_err), NO_MSG); \
498 #define SANITY_CHECK_RETURN_VALUE(_cond, _err, retval) \
501 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \
506 #define SANITY_CHECK_RETURN(_cond, _err) \
509 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \
514 #define SANITY_CHECK_EXIT(_cond, _err) \
517 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \
522 #endif /* DISABLE_SANITY_CHECKS */
524 /** @} */ /* end of Debug/error Utils group */
526 /** @} */ /* end of General Utils group */
528 #endif /* __ERROR_EXT_H */