1 /* Copyright (c) 2008-2012 Freescale Semiconductor, Inc 2 * All rights reserved. 3 * 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. 14 * 15 * 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 19 * later version. 20 * 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. 31 */ 32 33 34 /**************************************************************************//** 35 @File error_ext.h 36 37 @Description Error definitions. 38 *//***************************************************************************/ 39 40 #ifndef __ERROR_EXT_H 41 #define __ERROR_EXT_H 42 43 #if defined(NCSW_FREEBSD) 44 #include <sys/param.h> 45 #include <sys/errno.h> 46 #include <sys/pcpu.h> 47 #endif 48 49 #include "std_ext.h" 50 #include "xx_ext.h" 51 #include "core_ext.h" 52 53 54 55 56 /**************************************************************************//** 57 @Group gen_id General Drivers Utilities 58 59 @Description External routines. 60 61 @{ 62 *//***************************************************************************/ 63 64 /**************************************************************************//** 65 @Group gen_error_id Errors, Events and Debug 66 67 @Description External routines. 68 69 @{ 70 *//***************************************************************************/ 71 72 /****************************************************************************** 73 The scheme below provides the bits description for error codes: 74 75 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 76 | Reserved (should be zero) | Module ID | 77 78 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 79 | Error Type | 80 ******************************************************************************/ 81 82 #define ERROR_CODE(_err) ((((uint32_t)_err) & 0x0000FFFF) | __ERR_MODULE__) 83 84 #define GET_ERROR_TYPE(_errcode) ((_errcode) & 0x0000FFFF) 85 /**< Extract module code from error code (#t_Error) */ 86 87 #define GET_ERROR_MODULE(_errcode) ((_errcode) & 0x00FF0000) 88 /**< Extract error type (#e_ErrorType) from 89 error code (#t_Error) */ 90 91 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. */ 101 /* String: none. */ 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). */ 121 /* String: none. */ 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. */ 134 /* String: none. */ 135 ,E_INVALID_STATE /**< The operation is not allowed in current module state. */ 136 /* String: none. */ 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 147 are not suitable. 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). */ 182 /* String: none. */ 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. */ 188 /* String: none. */ 189 190 ,E_DUMMY_LAST /* NEVER USED */ 191 192 } e_ErrorType; 193 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. */ 200 201 ,EV_RX_DISCARD /**< Received packet discarded (by the driver, and only for 202 complete packets); 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. */ 208 /* String: none. */ 209 ,EV_TX_ERROR /**< Transmit error (by hardware/firmware); 210 Flags: usually status flags from the buffer descriptor. */ 211 /* String: none. */ 212 ,EV_NO_BUFFERS /**< System ran out of buffer objects; 213 Flags: zero. */ 214 /* String: none. */ 215 ,EV_NO_MB_FRAMES /**< System ran out of multi-buffer frame objects; 216 Flags: zero. */ 217 /* String: none. */ 218 ,EV_NO_SB_FRAMES /**< System ran out of single-buffer frame objects; 219 Flags: zero. */ 220 /* String: none. */ 221 ,EV_TX_QUEUE_FULL /**< Transmit queue is full; 222 Flags: zero. */ 223 /* String: none. */ 224 ,EV_RX_QUEUE_FULL /**< Receive queue is full; 225 Flags: zero. */ 226 /* String: none. */ 227 ,EV_INTR_QUEUE_FULL /**< Interrupt queue overflow; 228 Flags: zero. */ 229 /* String: none. */ 230 ,EV_NO_DATA_BUFFER /**< Data buffer allocation (from higher layer) failed; 231 Flags: zero. */ 232 /* String: none. */ 233 ,EV_OBJ_POOL_EMPTY /**< Objects pool is empty; 234 Flags: zero. */ 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; 240 Flags: zero. */ 241 /* String: none. */ 242 ,EV_PTP_RXTS_QUEUE_FULL /**< PTP Rx timestamps queue is full; 243 Flags: zero. */ 244 /* String: none. */ 245 ,EV_DUMMY_LAST 246 247 } e_Event; 248 249 250 /**************************************************************************//** 251 @Collection Debug Levels for Errors and Events 252 253 The level description refers to errors only. 254 For events, classification is done by the user. 255 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). 259 @{ 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 263 configuration. */ 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. */ 269 270 #define EVENT_DISABLED 0xFF /**< Disabled event (not reported at all) */ 271 272 /* @} */ 273 274 275 276 #define NO_MSG ("") 277 278 #ifndef DEBUG_GLOBAL_LEVEL 279 #define DEBUG_GLOBAL_LEVEL REPORT_LEVEL_WARNING 280 #endif /* DEBUG_GLOBAL_LEVEL */ 281 282 #ifndef ERROR_GLOBAL_LEVEL 283 #define ERROR_GLOBAL_LEVEL DEBUG_GLOBAL_LEVEL 284 #endif /* ERROR_GLOBAL_LEVEL */ 285 286 #ifndef EVENT_GLOBAL_LEVEL 287 #define EVENT_GLOBAL_LEVEL REPORT_LEVEL_MINOR 288 #endif /* EVENT_GLOBAL_LEVEL */ 289 290 #ifdef EVENT_LOCAL_LEVEL 291 #define EVENT_DYNAMIC_LEVEL EVENT_LOCAL_LEVEL 292 #else 293 #define EVENT_DYNAMIC_LEVEL EVENT_GLOBAL_LEVEL 294 #endif /* EVENT_LOCAL_LEVEL */ 295 296 297 #ifndef DEBUG_DYNAMIC_LEVEL 298 #define DEBUG_USING_STATIC_LEVEL 299 300 #ifdef DEBUG_STATIC_LEVEL 301 #define DEBUG_DYNAMIC_LEVEL DEBUG_STATIC_LEVEL 302 #else 303 #define DEBUG_DYNAMIC_LEVEL DEBUG_GLOBAL_LEVEL 304 #endif /* DEBUG_STATIC_LEVEL */ 305 306 #else /* DEBUG_DYNAMIC_LEVEL */ 307 #ifdef DEBUG_STATIC_LEVEL 308 #error "Please use either DEBUG_STATIC_LEVEL or DEBUG_DYNAMIC_LEVEL (not both)" 309 #else 310 int DEBUG_DYNAMIC_LEVEL = DEBUG_GLOBAL_LEVEL; 311 #endif /* DEBUG_STATIC_LEVEL */ 312 #endif /* !DEBUG_DYNAMIC_LEVEL */ 313 314 315 #ifndef ERROR_DYNAMIC_LEVEL 316 317 #ifdef ERROR_STATIC_LEVEL 318 #define ERROR_DYNAMIC_LEVEL ERROR_STATIC_LEVEL 319 #else 320 #define ERROR_DYNAMIC_LEVEL ERROR_GLOBAL_LEVEL 321 #endif /* ERROR_STATIC_LEVEL */ 322 323 #else /* ERROR_DYNAMIC_LEVEL */ 324 #ifdef ERROR_STATIC_LEVEL 325 #error "Please use either ERROR_STATIC_LEVEL or ERROR_DYNAMIC_LEVEL (not both)" 326 #else 327 int ERROR_DYNAMIC_LEVEL = ERROR_GLOBAL_LEVEL; 328 #endif /* ERROR_STATIC_LEVEL */ 329 #endif /* !ERROR_DYNAMIC_LEVEL */ 330 331 #define PRINT_FORMAT "[CPU%02d, %s:%d %s]" 332 #define PRINT_FMT_PARAMS PCPU_GET(cpuid), __FILE__, __LINE__, __FUNCTION__ 333 334 #if (!(defined(DEBUG_ERRORS)) || (DEBUG_ERRORS == 0)) 335 /* No debug/error/event messages at all */ 336 #define DBG(_level, _vmsg) 337 338 #define REPORT_ERROR(_level, _err, _vmsg) 339 340 #define RETURN_ERROR(_level, _err, _vmsg) \ 341 return ERROR_CODE(_err) 342 343 #if (REPORT_EVENTS > 0) 344 345 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) \ 346 do { \ 347 if (_ev##_LEVEL <= EVENT_DYNAMIC_LEVEL) { \ 348 XX_EventById((uint32_t)(_ev), (t_Handle)(_appId), (uint16_t)(_flg), NO_MSG); \ 349 } \ 350 } while (0) 351 352 #else 353 354 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) 355 356 #endif /* (REPORT_EVENTS > 0) */ 357 358 359 #else /* DEBUG_ERRORS > 0 */ 360 361 extern const char *dbgLevelStrings[]; 362 #if (REPORT_EVENTS > 0) 363 extern const char *eventStrings[]; 364 #endif /* (REPORT_EVENTS > 0) */ 365 366 char * ErrTypeStrings (e_ErrorType err); 367 368 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) 372 #else 373 #define DBG(_level, _vmsg) \ 374 do { \ 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__), \ 379 PRINT_FMT_PARAMS); \ 380 XX_Print _vmsg; \ 381 XX_Print("\r\n"); \ 382 } \ 383 } while (0) 384 #endif /* (defined(DEBUG_USING_STATIC_LEVEL) && (DEBUG_DYNAMIC_LEVEL < WARNING)) */ 385 386 387 #define REPORT_ERROR(_level, _err, _vmsg) \ 388 do { \ 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__), \ 393 PRINT_FMT_PARAMS, \ 394 ErrTypeStrings((e_ErrorType)GET_ERROR_TYPE(_err))); \ 395 XX_Print _vmsg; \ 396 XX_Print("\r\n"); \ 397 } \ 398 } while (0) 399 400 401 #define RETURN_ERROR(_level, _err, _vmsg) \ 402 do { \ 403 REPORT_ERROR(_level, (_err), _vmsg); \ 404 return ERROR_CODE(_err); \ 405 } while (0) 406 407 408 #if (REPORT_EVENTS > 0) 409 410 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) \ 411 do { \ 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__), \ 416 PRINT_FMT_PARAMS, \ 417 eventStrings[((_ev) - EV_NO_EVENT - 1)], \ 418 (uint16_t)(_flg)); \ 419 XX_Print _vmsg; \ 420 XX_Print("\r\n"); \ 421 XX_EventById((uint32_t)(_ev), (t_Handle)(_appId), (uint16_t)(_flg), NO_MSG); \ 422 } \ 423 } while (0) 424 425 #else /* not REPORT_EVENTS */ 426 427 #define REPORT_EVENT(_ev, _appId, _flg, _vmsg) 428 429 #endif /* (REPORT_EVENTS > 0) */ 430 431 #endif /* (DEBUG_ERRORS > 0) */ 432 433 434 /**************************************************************************//** 435 @Function ASSERT_COND 436 437 @Description Assertion macro. 438 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) 444 #else 445 #define ASSERT_COND(_cond) \ 446 do { \ 447 if (!(_cond)) { \ 448 XX_Print("*** ASSERT_COND failed " PRINT_FORMAT "\r\n", \ 449 PRINT_FMT_PARAMS); \ 450 XX_Exit(1); \ 451 } \ 452 } while (0) 453 #endif /* DISABLE_ASSERTIONS */ 454 455 456 #ifdef DISABLE_INIT_PARAMETERS_CHECK 457 458 #define CHECK_INIT_PARAMETERS(handle, f_check) 459 #define CHECK_INIT_PARAMETERS_RETURN_VALUE(handle, f_check, retval) 460 461 #else 462 463 #define CHECK_INIT_PARAMETERS(handle, f_check) \ 464 do { \ 465 t_Error err = f_check(handle); \ 466 if (err != E_OK) { \ 467 RETURN_ERROR(MAJOR, err, NO_MSG); \ 468 } \ 469 } while (0) 470 471 #define CHECK_INIT_PARAMETERS_RETURN_VALUE(handle, f_check, retval) \ 472 do { \ 473 t_Error err = f_check(handle); \ 474 if (err != E_OK) { \ 475 REPORT_ERROR(MAJOR, err, NO_MSG); \ 476 return (retval); \ 477 } \ 478 } while (0) 479 480 #endif /* DISABLE_INIT_PARAMETERS_CHECK */ 481 482 #ifdef DISABLE_SANITY_CHECKS 483 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) 488 489 #else /* DISABLE_SANITY_CHECKS */ 490 491 #define SANITY_CHECK_RETURN_ERROR(_cond, _err) \ 492 do { \ 493 if (!(_cond)) { \ 494 RETURN_ERROR(CRITICAL, (_err), NO_MSG); \ 495 } \ 496 } while (0) 497 498 #define SANITY_CHECK_RETURN_VALUE(_cond, _err, retval) \ 499 do { \ 500 if (!(_cond)) { \ 501 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \ 502 return (retval); \ 503 } \ 504 } while (0) 505 506 #define SANITY_CHECK_RETURN(_cond, _err) \ 507 do { \ 508 if (!(_cond)) { \ 509 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \ 510 return; \ 511 } \ 512 } while (0) 513 514 #define SANITY_CHECK_EXIT(_cond, _err) \ 515 do { \ 516 if (!(_cond)) { \ 517 REPORT_ERROR(CRITICAL, (_err), NO_MSG); \ 518 XX_Exit(1); \ 519 } \ 520 } while (0) 521 522 #endif /* DISABLE_SANITY_CHECKS */ 523 524 /** @} */ /* end of Debug/error Utils group */ 525 526 /** @} */ /* end of General Utils group */ 527 528 #endif /* __ERROR_EXT_H */ 529 530 531