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