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