blackhawk_tsc_diag.h (20059B)
1 /*********************************************************************************** 2 *********************************************************************************** 3 * * 4 * Revision : * 5 * * 6 * Description : Interface functions targeted to IP user * 7 * * 8 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 9 * 10 * Copyright 2007-2019 Broadcom Inc. All rights reserved. * 11 * No portions of this material may be reproduced in any form without * 12 * the written permission of: * 13 * Broadcom Corporation * 14 * 5300 California Avenue * 15 * Irvine, CA 92617 * 16 * * 17 * All information contained in this document is Broadcom Corporation * 18 * company private proprietary, and trade secret. * 19 */ 20 21 /** @file blackhawk_tsc_diag.h 22 * Diagnostic functions provided to IP User 23 */ 24 25 #ifndef BLACKHAWK_TSC_API_DIAG_H 26 #define BLACKHAWK_TSC_API_DIAG_H 27 28 #include "blackhawk_tsc_internal.h" 29 #include "blackhawk_tsc_ipconfig.h" 30 #include "common/srds_api_enum.h" 31 #include "common/srds_api_err_code.h" 32 #include "common/srds_api_uc_common.h" 33 #include "blackhawk_tsc_dependencies.h" 34 #include "blackhawk_tsc_usr_includes.h" 35 36 #ifndef DIAG_VERBOSE 37 #define DIAG_VERBOSE (0) 38 #endif 39 40 #define EYE_SCAN_NRZ_VERTICAL_IDX_MAX (62) 41 #define EYE_SCAN_NRZ_VERTICAL_STEP (2) 42 #define EYE_SCAN_PAM_VERTICAL_IDX_MAX (127) 43 #define EYE_SCAN_PAM_VERTICAL_STEP (1) 44 45 /** Eyescan Options Struct */ 46 struct blackhawk_tsc_eyescan_options_st { 47 uint32_t linerate_in_khz; 48 uint16_t timeout_in_milliseconds; 49 int8_t horz_max; 50 int8_t horz_min; 51 int8_t hstep; 52 int8_t vert_max; 53 int8_t vert_min; 54 int8_t vstep; 55 int8_t mode; 56 }; 57 58 59 /*----------------------------------------*/ 60 /* Display Core Config and Debug Status */ 61 /*----------------------------------------*/ 62 /** Display Core configurations (RAM config variables and config register fields). 63 * @param sa__ is an opaque state vector passed through to device access functions. 64 * @return Error Code, if generated (returns ERR_CODE_NONE if no errors) 65 */ 66 err_code_t blackhawk_tsc_display_core_config(srds_access_t *sa__); 67 68 /** Display current Core state. Read and displays core status variables and fields. 69 * @param sa__ is an opaque state vector passed through to device access functions. 70 * @return Error Code, if generated (returns ERR_CODE_NONE if no errors) 71 */ 72 err_code_t blackhawk_tsc_display_core_state(srds_access_t *sa__); 73 74 /** Column definition header for blackhawk_tsc_display_core_state() API output. 75 * To be called before blackhawk_tsc_display_core_state_line() API. 76 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 77 */ 78 err_code_t blackhawk_tsc_display_core_state_hdr(void); 79 80 /** Display current Core state in single line. Read and displays core status variables and fields. 81 * Call blackhawk_tsc_display_core_state_hdr() API before and blackhawk_tsc_display_core_state_legend() after 82 * calling this API to get a formatted core state display with legend. 83 * @param sa__ is an opaque state vector passed through to device access functions. 84 * @return Error Code, if generated (returns ERR_CODE_NONE if no errors) 85 */ 86 err_code_t blackhawk_tsc_display_core_state_line(srds_access_t *sa__); 87 88 /** Detailed description of each column in blackhawk_tsc_display_core_state_line() API output. 89 * To be called after blackhawk_tsc_display_core_state_line() API to display the legends. 90 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 91 */ 92 err_code_t blackhawk_tsc_display_core_state_legend(void); 93 94 /*-----------------------*/ 95 /* Temperature forcing */ 96 /*-----------------------*/ 97 98 /** Forces die temperature in degrees Ceisius (as integer). 99 * @param sa__ is an opaque state vector passed through to device access functions. 100 * @param die_temp Die temperature in degrees Celsius. (-255 will disable a previously forced value) 101 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 102 */ 103 err_code_t blackhawk_tsc_force_die_temperature (srds_access_t *sa__, int16_t die_temp); 104 105 /*-----------------------------------------------*/ 106 /* Envelope functions requested by Switch team */ 107 /*-----------------------------------------------*/ 108 109 /** Display current Core and Lane state. 110 * @param sa__ is an opaque state vector passed through to device access functions. 111 * @return Error Code, if generated (returns ERR_CODE_NONE if no errors) 112 */ 113 err_code_t blackhawk_tsc_display_state (srds_access_t *sa__); 114 115 /** Display current Core and Lane config. 116 * @param sa__ is an opaque state vector passed through to device access functions. 117 * @return Error Code, if generated (returns ERR_CODE_NONE if no errors) 118 */ 119 err_code_t blackhawk_tsc_display_config (srds_access_t *sa__); 120 121 /**************************************************/ 122 /* LANE Based APIs - Required to be used per Lane */ 123 /**************************************************/ 124 125 /** Function uses timestamps in uCode to check if heartbeat timer is programmed correctly 126 * for the COMCLK frequency it is running at * 127 * @param sa__ is an opaque state vector passed through to device access functions. 128 * @return Error Code if timestamp check fails (returns ERR_CODE_NONE if no errors) 129 */ 130 err_code_t blackhawk_tsc_test_uc_timestamp(srds_access_t *sa__); 131 132 /*-------------------*/ 133 /* Display Eye Scan */ 134 /*-------------------*/ 135 136 /** Displays Passive Eye Scan from -0.5 UI to 0.5UI to BER 1e-7. 137 * Function uses uC to acquire data. 138 * It also retrieves the data and displays it in ASCII-art style, where number N corresponds to 1e-N 139 * 140 * This function retrieves the data from uC in horizontal stripe fashion 141 * 142 * @param sa__ is an opaque state vector passed through to device access functions. 143 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 144 */ 145 err_code_t blackhawk_tsc_display_eye_scan(srds_access_t *sa__); 146 147 /** Start uC controller eye scan Function. 148 * Eye scan function provides a stripe of data at a time either vertical or horizontal. 149 * This function only initiates the processor actions. User must use blackhawk_tsc_read_eye_scan_stripe() function 150 * to get the data from uC. 151 * @param sa__ is an opaque state vector passed through to device access functions. 152 * @param direction specifies either EYE_SCAN_VERTICAL or EYE_SCAN_HORIZ striping 153 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 154 */ 155 err_code_t blackhawk_tsc_meas_eye_scan_start(srds_access_t *sa__, uint8_t direction); 156 157 /** Read a Stripe of eye scan data from uC. 158 * @param sa__ is an opaque state vector passed through to device access functions. 159 * @param *buffer must be of size 64 160 * @param *status returns a status word \n 161 * bit 15 - indicates the ey scan is complete \n 162 * bit 14 - indicates uC is slower than read access \n 163 * bit 13 - indicates uC is faster than read access \n 164 * bit 12-8 - reserved \n 165 * bit 7-0 - indicates amount of data in the uC buffer 166 * 167 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 168 */ 169 err_code_t blackhawk_tsc_read_eye_scan_stripe(srds_access_t *sa__, uint32_t *buffer, uint16_t *status); 170 171 /** Display Stripe of eye scan data to stdout and log. 172 * @param sa__ is an opaque state vector passed through to device access functions. 173 * @param y is the vertical step 124 to -124(Falcon16) 174 * @param *buffer must be of size 64 175 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 176 */ 177 err_code_t blackhawk_tsc_display_eye_scan_stripe(srds_access_t *sa__, int8_t y, uint32_t *buffer); 178 179 /** Display Eye scan header to stdout and log. 180 * @param i indicates the number of headers to display for parallel eye scan 181 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 182 */ 183 err_code_t blackhawk_tsc_display_eye_scan_header(int8_t i); 184 185 /** Display Eye scan footer to stdout and log. 186 * @param i indicates the number of footers to display for parallel eye scan 187 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 188 */ 189 err_code_t blackhawk_tsc_display_eye_scan_footer(int8_t i); 190 191 /** Check status of eye scan operation in uC. 192 * @param sa__ is an opaque state vector passed through to device access functions. 193 * @param *status returns a status word \n 194 * bit 15 - indicates the eye scan is complete \n 195 * bit 14 - indicates uC is slower than read access \n 196 * bit 13 - indicates uC is faster than read access \n 197 * bit 12:8 - reserved \n 198 * bit 7:0 - indicates amount of data in the uC buffer 199 * 200 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 201 */ 202 err_code_t blackhawk_tsc_read_eye_scan_status(srds_access_t *sa__, uint16_t *status); 203 204 /** Restores uC after running diagnostic eye scans. 205 * @param sa__ is an opaque state vector passed through to device access functions. 206 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 207 */ 208 err_code_t blackhawk_tsc_meas_eye_scan_done(srds_access_t *sa__); 209 210 /** Start a uC controlled BER scan function. 211 * This will tell the uC to make a number of BER measurements at different offsets 212 * and provide data back to API as a block of data. Several types of tests can be 213 * made including Passive (which can be run on any data pattern and does not affect 214 * datapath) or Intrusive (which can be run only when PRBS pattern is being used 215 * and will cause errors to occur). Intrusive test has a limited vertical range! 216 * 217 * @param sa__ is an opaque state vector passed through to device access functions. 218 * @param ber_scan_mode configures the type of test (use #srds_diag_ber_mode_enum) \n 219 * \verbatim 220 bit 7 - reserved 221 bit 6 - 1 = BER FAST scan mode (reduce minimum sample time from 0.1sec to 0.02sec 222 bit 5:4 - used for vertical intrusive test only (not recommended) 223 00 = move 1 slicer in direction bit0 (slicer selected for max range) 224 11 = move both, independent direction(not depend on bit0) legacy 40nm mode 225 01 = move only odd(depends on bit0) 226 10 = move only even(depends on bit0) 227 bit 3 - 1 = set passive scan to narrow vertical range(150mV); 0 = full range(250mV) 228 bit 2 - 1 = intrusive eye scan; 0 = passive 229 bit 1 - 1 = scan horizontal direction; 0 = scan vertical 230 bit 0 - 1 = scan negative portion of eye to center; 1 = scan positive \endverbatim 231 * @param timer_control sets the total test time in units of ~1.31 seconds 232 * @param max_error_control sets the error threshold for test in units of 16.(4=64 error threshold) 233 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 234 */ 235 err_code_t blackhawk_tsc_start_ber_scan_test(srds_access_t *sa__, uint8_t ber_scan_mode, uint8_t timer_control, uint8_t max_error_control); 236 237 /** Reads the BER scan data from uC after test has completed. 238 * @param sa__ is an opaque state vector passed through to device access functions. 239 * @param *errors is pointer to 32 element array of uint32 which will contain error data 240 * @param *timer_values is pointer to 32 element array of uint32 which will contain time data 241 * @param *cnt returns the number of samples 242 * @param timeout for polling data from uC (typically 2000) 243 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 244 */ 245 err_code_t blackhawk_tsc_read_ber_scan_data(srds_access_t *sa__, uint32_t *errors, uint32_t *timer_values, uint8_t *cnt, uint32_t timeout); 246 247 /** Extrapolate BER and display margin information 248 * @param sa__ is an opaque state vector passed through to device access functions. 249 * @param rate specifies the data rate in Hz 250 * @param ber_scan_mode the type of test used to take the data(use #srds_diag_ber_mode_enum) 251 * @param *total_errs is pointer to 32 element array of uint32 containing the error data 252 * @param *total_time is pointer to 32 element array of uint32 containing the time data 253 * @param max_offset is the maximum offset setting which is present in data (usually 31) 254 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 255 */ 256 err_code_t blackhawk_tsc_display_ber_scan_data (srds_access_t *sa__, USR_DOUBLE rate, uint8_t ber_scan_mode, uint32_t *total_errs, uint32_t *total_time, uint8_t max_offset); 257 258 /** Example eye margin projection API. 259 * This is an example function which uses the following API's to measure and display BER margin projections 260 * blackhawk_tsc_start_ber_scan_test(), blackhawk_tsc_read_ber_scan_data(), blackhawk_tsc_display_ber_scan_data(). 261 * 262 * @param sa__ is an opaque state vector passed through to device access functions. 263 * @param rate specifies the data rate in Hz 264 * @param ber_scan_mode the type of test used to take the data(use #srds_diag_ber_mode_enum) 265 * @param timer_control sets the total test time in units of ~1.31 seconds 266 * @param max_error_control sets the error threshold for test in units of 16.(4=64 errors) 267 * @return Error Code during data collection (returns ERR_CODE_NONE if no errors) 268 */ 269 err_code_t blackhawk_tsc_eye_margin_proj(srds_access_t *sa__, USR_DOUBLE rate, uint8_t ber_scan_mode, uint8_t timer_control, uint8_t max_error_control); 270 271 /*-----------------------------------------------*/ 272 /* Display Serdes Lane Config and Debug Status */ 273 /*-----------------------------------------------*/ 274 /** Display current lane configuration. 275 * Reads and displays all important lane configuration RAM variables and register fields. 276 * @param sa__ is an opaque state vector passed through to device access functions. 277 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 278 */ 279 err_code_t blackhawk_tsc_display_lane_config(srds_access_t *sa__); 280 281 /** Display current lane debug status. 282 * Reads and displays all vital lane user status and debug status. 283 * @param sa__ is an opaque state vector passed through to device access functions. 284 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 285 */ 286 err_code_t blackhawk_tsc_display_lane_debug_status(srds_access_t *sa__); 287 288 289 /*-----------------------------*/ 290 /* Display Serdes Lane State */ 291 /*-----------------------------*/ 292 /** Display current lane state. 293 * Reads and displays all important lane state values in a single line. 294 * \n Note: Call functions blackhawk_tsc_display_lane_state_hdr() before and blackhawk_tsc_display_lane_state_legend() after 295 * to get a formatted lane state display with legend 296 * @param sa__ is an opaque state vector passed through to device access functions. 297 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 298 */ 299 err_code_t blackhawk_tsc_display_lane_state(srds_access_t *sa__); 300 301 /** Column definition header for blackhawk_tsc display state. 302 * To be called before blackhawk_tsc_display_lane_state() function. 303 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 304 */ 305 err_code_t blackhawk_tsc_display_lane_state_hdr(void); 306 307 /** Detailed explanation of each column in blackhawk_tsc display state. 308 * To be called after blackhawk_tsc_display_lane_state() function to display the legends. 309 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 310 */ 311 err_code_t blackhawk_tsc_display_lane_state_legend(void); 312 313 /*---------------------------------------*/ 314 /* Required Serdes Diag/Debug routines */ 315 /*---------------------------------------*/ 316 /** Parameterized diagnostic function which provides comprehensive diagnostic and debug information 317 * This function is required to be implemented by upper level software to enable blackhawk_tsc support. 318 * @param sa__ is an opaque state vector passed through to device access functions. 319 * @param diag_level is a MASK style parameter to enable variable level of display. 320 * enum #srds_diag_level_enum can be used to help set the diag_level \n 321 * \verbatim 322 bit 0 - 1 = display extended lane state similar to existing falcon ext lane state. 323 0 = standard display lane state 324 bit 1 - display core state 325 bit 2 - event log 326 bit 3 - display fast eye scan 327 bit 4 - dump reg_dump 1 (core level registers) 328 bit 5 - dump reg_dump 2 (lane level registers) 329 bit 6 - dump core uC vars 330 bit 7 - dump lane uC vars 331 bit 8 - display lane debug state 332 bit 9 - display data for ber projection vertical 333 bit 10 - display data for ber projection horzontal 334 bit 11 - event log (safe), which does not involve micro for read \endverbatim 335 * 336 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 337 */ 338 err_code_t blackhawk_tsc_display_diag_data(srds_access_t *sa__, uint16_t diag_level); 339 340 /** Parameterized diagnostic function which access to all blackhawk_tsc control and status bits 341 * This function is required to be implemented by upper level software to enable blackhawk_tsc support. 342 * @param sa__ is an opaque state vector passed through to device access functions. 343 * @param type controls the type of access requested specified through enum #srds_diag_access_enum \n 344 * \verbatim 345 type = 0 - Register Read (param becomes count) 346 type = 1 - Register Read-Modify-Write (param becomes mask) 347 type = 2 - CORE RAM Read byte (data becomes count) 348 type = 3 - CORE RAM Read-Modify-Write byte (param becomes mask) 349 type = 4 - CORE RAM Read word (data becomes count) 350 type = 5 - CORE RAM Read-Modify-Write word (param becomes mask) 351 type = 6 - LANE RAM Read byte (data becomes count) 352 type = 7 - LANE RAM Read-Modify-Write byte (param becomes mask) 353 type = 8 - LANE RAM Read word (data becomes count) 354 type = 9 - LANE RAM Read-Modify-Write word (param becomes mask) 355 type = 10 - Global RAM Read byte (data becomes count) 356 type = 11 - Global RAM Read-Modify-Write byte (param becomes mask) 357 type = 12 - Global RAM Read word (data becomes count) 358 type = 13 - Global RAM Read-Modify-Write word (param becomes mask) 359 type = 14 - uC Command (addr becomes command; param becomes supp_info) 360 See microcode for available commands and further information. 361 type = 15 - Enable Breakboint 362 type = 16 - Next or Goto Breakpoint (addr becomes breakpoint #) 363 type = 17 - Read Breakpoint 364 type = 18 - Disable Breakpoint 365 type = 19 - Gather BER projection data (addr becomes ber_mode;data becomes max time;param becomes error threshold) 366 367 Note: Global RAM access will ONLY WORK on Cores with direct RAM access \endverbatim 368 * 369 * @param addr in most cases is the address of the register or RAM location 370 * @param data in most cases is the data to be written 371 * @param param is the multipurpose parameter and can be mask or other data 372 */ 373 err_code_t blackhawk_tsc_diag_access(srds_access_t *sa__, enum srds_diag_access_enum type, uint16_t addr, uint16_t data, uint16_t param); 374 375 376 /** FOR INTERNAL use only! 377 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 378 */ 379 380 err_code_t blackhawk_tsc_INTERNAL_poll_diag_data(srds_access_t *sa__, srds_info_t *blackhawk_tsc_info_ptr, uint16_t *status, uint8_t *diag_rd_ptr, uint8_t byte_count, uint32_t timeout_ms); 381 382 /*---------------------*/ 383 /* CL72/CL93 Status */ 384 /*---------------------*/ 385 386 /** Display CL93n72 Status of current lane. 387 * @return Error Code generated by API (returns ERR_CODE_NONE if no errors) 388 */ 389 err_code_t blackhawk_tsc_display_linktrn_status(srds_access_t *sa__); 390 391 392 #endif