blackhawk_tsc_functions.h (18478B)
1 /********************************************************************************* 2 ********************************************************************************* 3 * File Name : blackhawk_tsc_functions.h 4 * Created On : 29/04/2013 5 * Created By : Kiran Divakar 6 * Description: Header file with API functions for Serdes IPs 7 * Revision : 8 * 9 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 10 * 11 * Copyright 2007-2019 Broadcom Inc. All rights reserved. 12 * No portions of this material may be reproduced in any form without 13 * the written permission of: 14 * 15 * Broadcom Corporation 16 * 5300 California Avenue 17 * Irvine, CA 92617 18 * 19 * All information contained in this document is Broadcom Corporation 20 * company private proprietary, and trade secret. 21 */ 22 23 /** @file 24 * Protoypes of all API functions for engineering use 25 */ 26 27 #ifndef BLACKHAWK_TSC_API_FUNCTIONS_H 28 #define BLACKHAWK_TSC_API_FUNCTIONS_H 29 30 #ifdef _MSC_VER 31 #pragma warning ( disable : 4127 ) 32 #endif 33 34 #include "common/srds_api_err_code.h" 35 #include "common/srds_api_types.h" 36 #include "blackhawk_tsc_internal_error.h" 37 #include "blackhawk_tsc_usr_includes.h" 38 39 /**************************************************************************** 40 * @name Error-Code Storage Addresses. 41 * 42 * Used by error-checking expression-wrapper macros. Expands to the address 43 * where the macros are meant to store the error codes on which they operate, 44 * which depends on the target core and type of executable image being built. 45 * 46 * These are defined well ahead of the error-checking macros themselves to 47 * facilitate definition of RAM- and register-access macros generally used 48 * in their argyments. 49 */ 50 /**@{*/ 51 52 53 /** 54 * Error-code storage address. 55 * 56 * This is a standard API build that directs error-checking expression-wrapper 57 * macros to use a block-local error codes for efficient. local optimization. 58 */ 59 #define __ERR &__err 60 61 /**@}*/ 62 63 /**************************************************************************** 64 * @name Error-Checking Expression Wrappers 65 * 66 * These macros simplify checking and forwarding of error codes returned 67 * either directly or indirectly in the context of functions that themselves 68 * return error codes directly or indirectly. 69 * 70 * All expand to unterminated statements and dereference `__ERR' (defined as 71 * a macro in the same header) to access either private, block-internal error 72 * codes (`__err') or a common error-code cache (e.g. `global_err_code' in 73 * SerDes team post-silicon evaluation builds). 74 * 75 * Neither `__err' nor `__ERR' should be used directly outside the API; and 76 * their names may change to comply with the C Language standard reservation 77 * of identifiers beginning with `__' for use by compiler implementers. 78 * 79 * Great care is taken to ensure not only that error returns are checked but 80 * that use of an error-code cache (as in SerDes team post-silicon evaluation 81 * builds) does not cause "unused variable" warnings. 82 */ 83 /**@{*/ 84 85 /** 86 * Error-check a function call, returning error codes returned. 87 * 88 * Evaluates an expression (typically function call), stores its value into 89 * `*(__ERR)' and returns it from a containing function if it is unequal to 90 * `ERR_CODE_NONE'. 91 * 92 * EFUN() is intended for use in functions returning error codes directly to 93 * check calls to functions also returning error codes directly, e.g.: 94 * 95 * err_code_t foo(...) NOTE: remaining arguments elided 96 * { 97 * ... 98 * EFUN(wrc_core_s_rstb(0x0)); 99 * ... 100 * return ERR_CODE_NONE; 101 * } 102 */ 103 104 #define EFUN(expr) \ 105 do { \ 106 err_code_t __err = ERR_CODE_NONE; \ 107 *(__ERR) = (expr); \ 108 if (*(__ERR) != ERR_CODE_NONE) { \ 109 return blackhawk_tsc_error_report(sa__, *(__ERR)); \ 110 }\ 111 (void)__err; \ 112 } while(0) 113 114 /** 115 * Error-check a function call, goto "Exit" label defined by parent function using CFUNs. 116 * 117 * Evaluates an expression (typically function call), stores its value into 118 * Exit_Status (a local variable to the parent function). 119 * 120 * If no error, continue.. 121 * if there is an error, updates *(__ERR) if it hasnt been updated with a non-zero error code already. 122 * 123 * 124 * CFUN() is intended for use in functions returning error codes directly to 125 * check calls to functions also returning error codes directly, e.g.: 126 * 127 * err_code_t foo(...) NOTE: remaining arguments elided 128 * { 129 * ... 130 * CFUN(wrc_core_s_rstb(0x0)); 131 * ... 132 * Exit: 133 * / * cleanup (free memory, close filehandles etc..) * / 134 * return ERR_CODE_NONE; 135 * } 136 */ 137 138 #define CFUN(expr) \ 139 do { \ 140 err_code_t __err = ERR_CODE_NONE; \ 141 Exit_Status = (expr); \ 142 if (Exit_Status != ERR_CODE_NONE) {\ 143 if (!*(__ERR) ) { \ 144 *(__ERR) = Exit_Status; \ 145 }\ 146 goto Exit; \ 147 }\ 148 (void)__err; \ 149 } while(0) 150 151 /** 152 * Error-check a statement, returning error codes forwarded. 153 * 154 * Evaluates an expression (typically unterminated statement) that may modify 155 * `*(__ERR)' and returns it from a containing function if it is unequal to 156 * `ERR_CODE_NONE'. 157 * 158 * ESTM() is intended for use in functions returning error codes directly to 159 * check calls to functions returning error codes indirectly, e.g.: 160 * 161 * err_code_t foo(...) NOTE: remaining arguments elided 162 * { 163 * uint8_t rst; 164 * ... 165 * ESTM(rst = rdc_core_s_rstb()); 166 * ... 167 * return ERR_CODE_NONE; 168 * } 169 */ 170 171 #define ESTM(expr) \ 172 do { \ 173 err_code_t __err; \ 174 *(__ERR) = ERR_CODE_NONE; \ 175 (expr); \ 176 if (*(__ERR) != ERR_CODE_NONE) \ 177 return blackhawk_tsc_error_report(sa__, *(__ERR)); \ 178 (void)__err; \ 179 } while(0) 180 181 /** 182 * Error-check a function call, defaulting when forwarding error codes 183 * returned. 184 * 185 * In a function taking an argument `err_code_t *err_code_p' in lieu of 186 * returning an error code directly, evaluates an expression (typically 187 * function call), stores its value into `*(__ERR)', combines this (bitwise 188 * inclusive ore) into `*(err_code_p)', and returns a default value if either 189 * `*(__ERR)' or `*(err_code_p)' is not `ERR_CODE_NONE'. 190 * 191 * EPFUN2() is intended for use in functions returning error codes indirectly 192 * to check calls to functions returning error codes directly, e.g.: 193 * 194 * uint8_t foo(err_code_t *err_code_p, ...) NOTE: remaining arguments elided 195 * { 196 * uint8_t result = 0x0; 197 * ... 198 * EPFUN2(wrc_core_s_rstb(0x0), 0x1); 199 * ... 200 * return result; 201 * } 202 */ 203 204 #define EPFUN2(expr, on_err) \ 205 do { \ 206 err_code_t __err; \ 207 *(__ERR) = (expr); \ 208 *(err_code_p) |= *(__ERR); \ 209 if ((*(err_code_p) != ERR_CODE_NONE) \ 210 || (*(__ERR) != ERR_CODE_NONE)) \ 211 return (on_err); \ 212 (void)__err; \ 213 } while(0) 214 215 /** 216 * Error-check a statement, defaulting when forwarding error codes forwarded. 217 * 218 * In a function taking an argument `err_code_t *err_code_p' in lieu of 219 * returning an error code directly, evaluates an expression (typically 220 * unterminated statement), stores its value into `*(__ERR)', combines this 221 * (bitwise inclusive ore) into `*(err_code_p)', and returns a default value 222 * if either `*(__ERR)' or `*(err_code_p)' is not `ERR_CODE_NONE'. 223 * 224 * EPSTM2() is intended for use in functions returning error codes indirectly 225 * to check calls to functions also returning error codes indirectly, e.g.: 226 * 227 * uint8_t foo(err_code_t *err_code_p, ...) NOTE: remaining arguments elided 228 * { 229 * uint8_t result; 230 * ... 231 * EPSTM(result = rdc_core_s_rstb(), 0x1); 232 * ... 233 * return result; 234 * } 235 */ 236 237 #define EPSTM2(expr, on_err) \ 238 do { \ 239 err_code_t __err; \ 240 *(__ERR) = ERR_CODE_NONE; \ 241 (expr); \ 242 *(err_code_p) |= *(__ERR); \ 243 if ((*(err_code_p )!= ERR_CODE_NONE) \ 244 || (*(__ERR) != ERR_CODE_NONE)) \ 245 return (on_err); \ 246 (void)__err; \ 247 } while(0) 248 249 /** 250 * Error-check a function call, defaulting to zero when forwarding error codes 251 * returned. 252 * 253 * Supplies a default value of zero to EPFUN2() to reduce clutter in the most 254 * common case. 255 * 256 * EPFUN() is intended for use in functions returning error codes indirectly 257 * to check calls to functions returning error codes directly, e.g.: 258 * 259 * uint8_t foo(err_code_t *err_code_p, ...) NOTE: remaining arguments elided 260 * { 261 * uint8_t result; NOTE: determined below, detail elided 262 * ... 263 * EPFUN(wrc_core_s_rstb(0x0)); 264 * ... 265 * return result; 266 * } 267 */ 268 269 #define EPFUN(expr) EPFUN2((expr), 0) 270 271 /** 272 * Error-check a statement, defaulting to zero when forwarding error codes 273 * forwarded. 274 * 275 * Supplies a default value of zero to EPSTM2() to reduce clutter in the most 276 * common case. 277 * 278 * EPSTM() is intended for use in functions returning error codes indirectly 279 * to check calls to functions also returning error codes indirectly, e.g.: 280 * 281 * uint8_t foo(err_code_t *err_code_p, ...) NOTE: remaining arguments elided 282 * { 283 * uint8_t result; 284 * ... 285 * EPSTM(result = rdc_core_s_rstb()); 286 * ... 287 * return result; 288 * } 289 */ 290 291 #define EPSTM(expr) EPSTM2((expr), 0) 292 293 /** 294 * Invoke a function with automatic return of error on NULL result. 295 * 296 * ENULL() is intended for use in functions returning error codes directly to 297 * check calls to functions returning pointers, e.g.: 298 * 299 * err_code_t foo(...) NOTE: remaining arguments elided 300 * { 301 * ... 302 * ENULL(strchr("foo", 'q')); 303 * ... 304 * return ERR_CODE_NONE; 305 * } 306 */ 307 #define ENULL(expr) \ 308 EFUN((((void *)0!=(expr))?ERR_CODE_NONE:ERR_CODE_BAD_PTR_OR_INVALID_INPUT)) 309 310 /** 311 * Invoke a function with automatic forward of error on NULL result. 312 * 313 * EPNULL() is intended for use in functions returning error codes indirectly 314 * to check calls to functions returning pointers, e.g.: 315 * 316 * uint8_t foo(err_code_t *err_code_p, ...) NOTE: remaining arguments elided 317 * { 318 * uint8_t result; NOTE: determined below, detail elided 319 * ... 320 * EPNULL(strchr(foo, 'q')); 321 * ... 322 * return result; 323 * } 324 */ 325 #define EPNULL(expr) \ 326 EPFUN((((void *)0!=(expr))?ERR_CODE_NONE:ERR_CODE_BAD_PTR_OR_INVALID_INPUT)) 327 328 /** 329 * Invoke USR_PRINTF(()) with non-error-code-generating arguments. 330 * 331 * Note that the single argument is a parenthesized argument list to be 332 * passed to USR_PRINTF(()). 333 * 334 * EFUN_PRINTF(()) is intended for use in functions returning error codes 335 * directly, with an argument list the elements of which do not generate 336 * error codes of any kind, e.g.: 337 * 338 * err_code_t foo(...) NOTE: remaining arguments elided 339 * { 340 * ... 341 * EFUN_PRINTF(("%u", 1)); 342 * ... 343 * return ERR_CODE_NONE; 344 * } 345 */ 346 #define EFUN_PRINTF(paren_arg_list) USR_PRINTF(paren_arg_list) 347 348 /** 349 * Invoke USR_PRINTF(()) with error-code-generating arguments that would 350 * otherwise be handled by ESTM(). 351 * 352 * Note that the single argument is a parenthesized argument list to be 353 * passed to USR_PRINTF(()). 354 * 355 * EFUN_PRINTF(()) is intended for use in functions returning error codes 356 * directly, with an argument list the elements of which may generate error 357 * codes indirectly, e.g.: 358 * 359 * err_code_t foo(...) NOTE: remaining arguments elided 360 * { 361 * ... 362 * ESTM_PRINTF(("%u", rdc_core_s_rstb())); 363 * ... 364 * return ERR_CODE_NONE; 365 * } 366 */ 367 #define ESTM_PRINTF(paren_arg_list) \ 368 do { \ 369 err_code_t __err; \ 370 *(__ERR) = ERR_CODE_NONE; \ 371 USR_PRINTF(paren_arg_list); \ 372 if (*(__ERR) != ERR_CODE_NONE) \ 373 return blackhawk_tsc_error_report(sa__, *(__ERR)); \ 374 (void)__err; \ 375 } while(0) 376 377 /** 378 * Invoke possibly-remapped 'memset()' and, if it returns NULL, force an 379 * error return. 380 * 381 * Ordinarily, standard implementations of 'memset' will return NULL only if 382 * passed a NULL destination address, and *may already* have overwritten an 383 * inappropriate address range before returning: nevertheless, a specialized 384 * implementation could use a NULL return to indicate other failures. In 385 * either case, execution should not be allowed to proceed on NULL return. 386 */ 387 #define ENULL_MEMSET(mem, val, num) ENULL((USR_MEMSET((mem), (val), (num)))) 388 389 /** 390 * Invoke possibly-remapped 'memset()' and, if it returns NULL, force an 391 * error to be forwarded. 392 * 393 * Ordinarily, standard implementations of 'memset' will return NULL only if 394 * passed a NULL destination address, and *may already* have overwritten an 395 * inappropriate address range before returning: nevertheless, a specialized 396 * implementation could use a NULL return to indicate other failures. In 397 * either case, execution should not be allowed to proceed on NULL return. 398 */ 399 #define EPNULL_MEMSET(mem, val, num) EPNULL((USR_MEMSET((mem), (val), (num)))) 400 401 /** 402 * Invoke possibly-remapped 'strcpy()' and, if it returns NULL, force an 403 * error return. 404 * 405 * Ordinarily, standard implementations of 'strcpy' will return NULL only if 406 * passed a NULL destination address, and *may already* have overwritten an 407 * inappropriate address range before returning: nevertheless, a specialized 408 * implementation could use a NULL return to indicate other failures. In 409 * either case, execution should not be allowed to proceed on NULL return. 410 */ 411 #define ENULL_STRCPY(dst, src) ENULL((USR_STRCPY((dst), (src)))) 412 413 /** 414 * Invoke possibly-remapped 'strcpy()' and, if it returns NULL, force an 415 * error to be forwarded. 416 * 417 * Ordinarily, standard implementations of 'strcpy' will return NULL only if 418 * passed a NULL destination address, and *may already* have overwritten an 419 * inappropriate address range before returning: nevertheless, a specialized 420 * implementation could use a NULL return to indicate other failures. In 421 * either case, execution should not be allowed to proceed on NULL return. 422 */ 423 #define EPNULL_STRCPY(dst, src) EPNULL((USR_STRCPY((dst), (src)))) 424 425 /** 426 * Invoke possibly-remapped 'strncat()' and, if it returns NULL, force an 427 * error return. 428 * 429 * Ordinarily, standard implementations of 'strncat' will return NULL only if 430 * passed a NULL destination address, and *may already* have overwritten an 431 * inappropriate address range before returning: nevertheless, a specialized 432 * implementation could use a NULL return to indicate other failures. In 433 * either case, execution should not be allowed to proceed on NULL return. 434 */ 435 #define ENULL_STRNCAT(dst, src, num) ENULL((USR_STRNCAT((dst), (src), (num)))) 436 437 /** 438 * Invoke possibly-remapped 'strncat()' and, if it returns NULL, force an 439 * error to be forwarded. 440 * 441 * Ordinarily, standard implementations of 'strncat' will return NULL only if 442 * passed a NULL destination address, and *may already* have overwritten an 443 * inappropriate address range before returning: nevertheless, a specialized 444 * implementation could use a NULL return to indicate other failures. In 445 * either case, execution should not be allowed to proceed on NULL return. 446 */ 447 #define EPNULL_STRNCAT(dst, src, num) EPNULL((USR_STRNCAT((dst), (src), (num)))) 448 449 /**@}*/ 450 451 /**************************************************************************** 452 * @name Display Utility Macros 453 */ 454 /**@{*/ 455 456 /** Display a signed integer variable. */ 457 #define DISP(x) ESTM_PRINTF(("%s = %d\n", #x, x)) 458 459 /** Display an unsigned integer variable. */ 460 #define DISPU(x) ESTM_PRINTF(("%s = %u\n", #x, x)) 461 462 /** Display a floating point variable. */ 463 #define DISPF(x) ESTM_PRINTF(("%s = %f\n", #x, x)) 464 465 /** Display an integer variable in hex. */ 466 #define DISPX(x) ESTM_PRINTF(("%s = 0x%x\n", #x, x)) 467 468 #define REVERSE_BYTES_2(param) \ 469 ((((uint16_t)param)&0xFF)<<8) | ((((uint16_t)param)>>8)&0xFF) 470 471 #define REVERSE_BYTES_4(param) \ 472 (((uint32_t)param&0xFF)<<24) | ((((uint32_t)param>>8)&0xFF)<<16) | ((((uint32_t)param>>16)&0xFF)<<8) | (((uint32_t)param>>24)&0xFF) 473 474 #define ADJUST_ENDIANNESS(_struct_, _param_) \ 475 ((_struct_.big_endian != big_endian) ? ((sizeof(_struct_._param_) == 2) ? REVERSE_BYTES_2(_struct_._param_) : (sizeof(_struct_._param_) == 4) ? REVERSE_BYTES_4(_struct_._param_) : _struct_._param_) : _struct_._param_ ) 476 477 /** Read and display the value of a lane register field in decimal. */ 478 #define DISP_REG(x) ESTM_PRINTF(("%s = %d\n", #x, rd_##x())) 479 480 /** Read and display the value of a lane register field in hex. */ 481 #define DISP_REGX(x) ESTM_PRINTF(("%s = 0x%x\n", #x, rd_##x())) 482 483 /** Read and display the value of a core register field in hex. */ 484 #define DISP_REGC(x) ESTM_PRINTF(("%s = 0x%x\n", #x, rdc_##x())) 485 486 /** Display a single member of a lane struct. */ 487 #define DISP_LN_VARS(name,param,format) \ 488 do { \ 489 ESTM_PRINTF(("%-16s\t",name)); \ 490 for(i=0;i<num_lanes;i++) { \ 491 ESTM_PRINTF((format,ADJUST_ENDIANNESS(lane_st[i], param))); \ 492 } \ 493 EFUN_PRINTF(("\n")); \ 494 } while (0) 495 496 /** Display four members of a lane struct. */ 497 #define DISP_LNQ_VARS(name,param1,param2,param3,param4,format) \ 498 do { \ 499 ESTM_PRINTF(("%-16s\t ",name)); \ 500 for(i=0;i<num_lanes;i++) { \ 501 ESTM_PRINTF((format,ADJUST_ENDIANNESS(lane_st[i], param1),ADJUST_ENDIANNESS(lane_st[i], param2),ADJUST_ENDIANNESS(lane_st[i], param3),ADJUST_ENDIANNESS(lane_st[i], param4))); \ 502 } \ 503 EFUN_PRINTF(("\n")); \ 504 } while (0) 505 /**@}*/ 506 507 /**************************************************************************** 508 * @name Arithmetic Utility Macros 509 */ 510 /**@{*/ 511 512 /** 513 * Clockwise difference between phase counters. 514 */ 515 #define dist_cw(a,b) (((a)<=(b))?((b)-(a)):((uint16_t)512-(a)+(b))) 516 517 /** 518 * Counter-clockwise difference between phase counters 519 */ 520 #define dist_ccw(a,b) (((a)>=(b))?((a)-(b)):((uint16_t)512+(a)-(b))) 521 522 /**@}*/ 523 524 /* A macro to handle compile warnings about unused variables/parameters 525 irrespective of whether __attribute__((unused)) is supported or not */ 526 #define UNUSED(__x__) (void)(__x__) 527 528 /* 529 * Macro to set a variable called error_seen to 1 if expression results in error. 530 * _expr_ (ex. register reads) 531 */ 532 #define CHECK_ERR(_expr_) \ 533 (_expr_);\ 534 if (*(__ERR) != ERR_CODE_NONE) { \ 535 error_seen = 1;\ 536 } 537 538 #endif