diff options
| -rw-r--r-- | mpm/python/usrp_mpm/cores/CMakeLists.txt | 5 | ||||
| -rw-r--r-- | mpm/python/usrp_mpm/cores/eyescan.py | 839 | ||||
| -rw-r--r-- | mpm/python/usrp_mpm/cores/nijesdcore.py | 20 |
3 files changed, 860 insertions, 4 deletions
diff --git a/mpm/python/usrp_mpm/cores/CMakeLists.txt b/mpm/python/usrp_mpm/cores/CMakeLists.txt index bbed68eb3..39a15c0ed 100644 --- a/mpm/python/usrp_mpm/cores/CMakeLists.txt +++ b/mpm/python/usrp_mpm/cores/CMakeLists.txt @@ -1,7 +1,7 @@ # -# Copyright 2017 Ettus Research, National Instruments Company +# Copyright 2017-2018 Ettus Research, National Instruments Company # -# SPDX-License-Identifier: GPL-3.0 +# SPDX-License-Identifier: GPL-3.0-or-later # SET(USRP_MPM_FILES ${USRP_MPM_FILES}) @@ -9,6 +9,7 @@ SET(USRP_MPM_CORE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/__init__.py ${CMAKE_CURRENT_SOURCE_DIR}/tdc_sync.py ${CMAKE_CURRENT_SOURCE_DIR}/nijesdcore.py + ${CMAKE_CURRENT_SOURCE_DIR}/eyescan.py ${CMAKE_CURRENT_SOURCE_DIR}/white_rabbit.py ) LIST(APPEND USRP_MPM_FILES ${USRP_MPM_CORE_FILES}) diff --git a/mpm/python/usrp_mpm/cores/eyescan.py b/mpm/python/usrp_mpm/cores/eyescan.py new file mode 100644 index 000000000..b6e24ef13 --- /dev/null +++ b/mpm/python/usrp_mpm/cores/eyescan.py @@ -0,0 +1,839 @@ +# +# Copyright 2018 Ettus Research, a National Instruments Company +# +# SPDX-License-Identifier: GPL-3.0-or-later +# +""" +RX Eye Scan utility for GTX transceivers on 7-series FPGAs. + +Introduction: + + A RX eye scan provides a mechanism to validate the receiver's eye margin after the + transceiver's equalizer in high-speed digital transmission lines. + The principle of operation of an eye scan is the comparison between the data sampled + at the nominal center of the eye, and the data sampled at an offset (horizontal and + vertical) from the said nominal center. + A miscomparison between the nominal data and the offset data yields a bit error, and + the Bit Error Rate (BER) is the ratio of bit errors to the total number of samples + compared. A 2-D statistical eye can be obtained by determining the BER at multiple + offset coordinates (horizontal, vertical) in a given 2-D range. Each offset coordinate + has two components: phase offset (horizontal), and voltage offset (vertical). + + The 7-series FPGAs' transceivers include hardware that allows us to perfom parallel + sampling on the same signal: one at the nominal center, and one with certain offset. + The hardware consists on two separate samplers, one which signal can be offset. + Also, a sample counter, that keeps track of the number of samples compared at a given + offset; as well as an error counter that tracks the miscomparisons detected. These two + counters are accessible via the transceiver's Dynamic Reconfiguration Port (DRP). + Finally, a state machine, configurable through the DRP, controls the BER measurement + at a given offset. + The second sampler path can apply both a phase and a voltage offset to the signal. + Thanks to this parallel sampler, one may perform eye scan measurements without + affecting the link's integrity (i.e. the nominal sampled data remains untouched). + + +Important considerations: + + - This tool only supports 7-Series FPGAs (GTX only). + - The tool needs the NI's JESD core IP and MPM driver to access the DRP of the GTs. + - Currently, a .pes (Python Eye Scan) custom binary file is generated, which includes + metadata and the sample/error counters results at each offset for the scanned GT(s). + This file is further processed and visualized with an internal set of LabVIEW VIs. + + +Using the Eye Scan tool: + + 1. Determine the transceiver(s) configuration. + Some parameters are defined with the GT instantiation in the FPGA. These need to + be known by the Eye Scan tool in order to function properly: + Equalization mode. + Low-Power Mode (LPM) or Decision Feedback Equalization (DFE). + Please refer to UG476 (p. 184) for further details. + Valid values for this tool: 'LMP' or 'DFE'. + RXOUT_DIV. + This attribute controls the setting for the RX serial clock divider. + Please refer to UG476 (p. 213) for further details. + Valid values for this tool: 1, 2, 4, 8, 16. + RX_INT_DATAWIDTH. + Width of valid data on Rdata and Sdata buses is RX fabric data width. + Please refer to UG476 (p. 213) for further details. + Valid values for this tool: 16, 20, 32, 40. + + 2. Determine the Eye Scan measurement configuration. + The eye scan measurement's confidence/resolution depends on some parameters, + depending upon their values, the time to perform the scan will change: + Prescale. + Controls the prescaling of the sample count to keep both sample count and + error count in reasonable precision within the 16-bit register range. + The higher the prescale value, the more time the eye scan takes, but also + the lower BER floor (i.e. best eye margin statistics). + Please refer to UG476 (p. 214) for further details. + Valid values for this tool: 0 to 31. + Horizontal range. + Defines the phase offset limits and step that the tool will use to iterate + in the horizontal axis during the measurement. + Valid range is -32 to 32 (full range), corresponding to -0.5 UI to 0.5 UI + Definition example: {'start':-32 , 'stop':32 , 'step': 1} + Vertical range. + Defines the voltage offset limits and step that the tool will use to iterate + in the vertical axis during the measurement. + Valid range is -127 to 127 (full range), corresponding to 0.39 % + increments. + Definition example: {'start':-127, 'stop':127, 'step': 2} + + 3. Determine which GT(s) will be scanned. + The tool supports single scan and parallel multi-lane scan. The previous GT + configuration (from 1), and the measurement configuration (from 2) applies + for all the GTs scanned in a single run. Thus, if one requires a different scan + per GT, a EyeScanTool object must be created each time with different parameters. + The tool receives a 1-D array, which each element must be a valid GT number that + the NI JESD core has access to. + Examples: [0] or [0, 1] or [0, 1, 2, 3]. + + 4. Obtain a JESD core MPM object. + The Eye Scan tool relies on the JESD core IP in the FPGA to talk to the GTs + through their DRP, thus a MPM driver object for this core must be available + upon creation of the EyeScanTool object. + Please refer to nijesdcore.py for further documentation. + + 5. Create an Eye Scan tool MPM object. + Once the configuration is defined and a MPM JESD core object is available, one + may proceed to create and initialize an EyeScanTool object. + The genrated .pes file will be saved to the location given by the SAVE_DIR, which + default value is set to a folder named "eyescan" in the home directory. + One may change the save location by including the SAVE_DIR attribute at init. + Assuming the EyeScanTool class has been imported to the calling file, here is + an object creation example: + args = {'rxout_div': 2, 'rx_int_datawidth': 20, 'eq_mode': 'LPM', 'prescale': 1, + 'SAVE_DIR': "/home/root/my_dir/"} + eyescan_tool = EyeScanTool(jesdcore=jesdcore_object, + slot_idx=0, + **args) + + 6. Perform the Eye Scan measurement! + With the EyeScanTool object created and initialized, one may proceed to start + the measurement by calling the function eyescan_full_scan(...). + This function receives the array of GTs to scan, the horizontal range, and the + vertical range. It returns the name of the PES file (automatically generated). + + Here is an example on how to start the scan: + scan_lanes = [0, 1, 2, 3] + hor_range = {'start':-32 , 'stop':32 , 'step': 2} + ver_range = {'start':-127, 'stop':127, 'step': 2} + pes_file_name = eyescan_tool.eyescan_full_scan(scan_lanes, hor_range, ver_range) + + 7. Process and visualize the PES file. + The resulting .pes binary file must be manually copied to a known location for + LabVIEW access (i.e. a Windows machine running LV). + Currently, two different file post-processing methods are supported: + Single lane full scans. + When only one lane is measured (e.g. scan_lanes = [0]), it is recommended to + use the Single-Lane VI to process/visualize the results. + Multiple lane full scans. + When multiple lanes are measured (e.g. scan_lanes = [0, 1, 2, 3]), it is + recommended to use the Multi-Lane VI to process/visualize the results. + These VIs are for NI/Ettus internal use only. For further details, please contact + Humberto Jimenez at humberto.jimenez@ni.com. + + +Theory of operation: + + As explained in the introductory section, the main two elements to perform a rx + margin analysis are a sample counter and an error counter. These two are provided + by the GT instantiation at the FPGA. This tools implements the algorithm to control + the Eye Scan measurement state machine for the given GT(s) and retreive the counts. + This task is repetead over and over again through the vertical and horizontal ranges + specified by the user. The results for each offset coordinate are stored in a custom + binary file (.pes) that is then processed (BER calculation) and visualized. + + When a EyeScanTool object is created (i.e. __init__ is called), the "fixed" + configuration parameters for the GT(s) instantiation is defined. Also, the provided + JESD core object is verified to make sure it contains the method implementations to + access the Dynamic Reconfiguration Port (DRP) of the desired GT(s). + With an EyeScanTool object created and initialized, the user only needs to call the + eyescan_full_scan(...) method; which handles the measurement configuration, the binary + file creation, the GT(s) configuration, and the measurement sweep across the ranges. + + +Future work ideas: + + 1. Generate the eye scan results in human-readable fashion (i.e. ascii encoded + instead of binary data). + 2. Add Bit Error Rate (BER) calculation for each offset within the tool, instead of + just spitting samples and errors counters. + 3. Develop a open-source data visualization tool to enable non-LabVIEW users to + process and visualize the eye scan results (pes file). +""" + +import os +import time +import math +import datetime +from builtins import object +from usrp_mpm.mpmlog import get_logger + +class EyeScanTool(object): + """ + Provides a library to perform Eye Scan measurements using the NI JESD core. + """ + + MGT_TYPE = "GTX" + VER_MAJOR = "1" + VER_MINOR = "0" + SAVE_DIR = "/home/root/eyescan/" + + # Set this value according to the status message printing rate desired. (Min=1) + # E.g. PRINT_STATUS_EVERY = 1 will print a status message every offset measurement. + PRINT_STATUS_EVERY = 10 + + lanes = None + # Array that defines the available lanes to measure. + lane_num = None + # Defines the currently global controled lane number. + def set_global_lane(self, lane_num=None): + """ + This method sets the global lane number variable being accessed, as well as + configures the DRP to target the given lane number. + """ + # Set the global variable and the DRP target with the given lane number. + if lane_num is not None: + self.log.trace("Setting lane %d as the global variable...", lane_num) + # Set the global variable. + self.lane_num = lane_num + # Set the DRP target in the JESD core to the given lane number. + self.jesdcore.set_drp_target('mgt', self.lane_num) + else: + self.log.trace("Unsetting the lane global variable...") + # Unset the global variable. + self.lane_num = None + # Disable DRP target for the given lane number. + self.jesdcore.disable_drp_target() + + + def __init__(self, jesdcore, slot_idx=0, **kwargs): + def validate_config(): + """ + This function validates the configuration parameters' ranges. + """ + assert (0 <= self.prescale) and (self.prescale <= 31) + assert self.rxout_div in (1, 2, 4, 8, 16) + assert self.rx_int_datawidth in (16, 20, 32, 40) + assert self.eq_mode.upper() in ('LPM', 'DFE') + self.log.debug("Valid Eye Scan configuration: prescale=%d rxout_div=%d" + " rx_int_datawidth=%d eq_mode=%s", + self.prescale, self.rxout_div, self.rx_int_datawidth, self.eq_mode) + # + self.slot_idx = slot_idx + self.log = get_logger("EyeScanTool-{}".format(self.slot_idx)) + self.log.info("Initializing Eye Scan Tool...") + self.jesdcore = jesdcore + assert hasattr(self.jesdcore, 'set_drp_target') + assert hasattr(self.jesdcore, 'disable_drp_target') + assert hasattr(self.jesdcore, 'drp_access') + # Some global parameters defined. + # + # Control the prescaling of the sample count to keep both sample + # count and error count in reasonable precision within the 16-bit + # register range. + # Valid values: from 0 to 31. + self.prescale = 0 + # + # QPLL/CPLL output clock divider D for the RX datapath. + # Valid values: 1, 2, 4, 8, 16. + self.rxout_div = 1 + # + # Defines the width of valid data on Rdata and Sdata buses. + # Valid values: 16, 20, 32, 40. + self.rx_int_datawidth = 16 + # + # Equalizer mode: LPM linear eq. or DFE eq. + # When in DFE mode (RXLPMEN=0), due to the unrolled first DFE tap, + # two separate eye scan measurements are needed, one at +UT and + # one at -UT, to measure the TOTAL BER at a given vertical and + # horizontal offset. + # Valid values = 'LPM', 'DFE'. + self.eq_mode = 'LPM' + # + # Overwrite the default configuration parameters with the ones given + # by the user (host) through kwargs. + for key, new_val in list(kwargs.items()): + if hasattr(self, key) and (new_val != getattr(self, key)): + self.log.trace("Overwriting {0}... default:{1} user:{2}" + .format(key, getattr(self, key), new_val)) + setattr(self, key, new_val) + # Validate configuration attributes' values. + validate_config() + + + def parse_ranges(self, + hor_range={'start':-32 , 'stop':32 , 'step': 1}, + ver_range={'start':-127, 'stop':127, 'step': 2}): + """ + This function extracts parameters from the Eye Scan phase and voltage ranges + used in measurement loops and height/width calculation. + The function returns a list with the following keys: + parsed_ranges = {'hor_start', 'hor_stop', 'hor_iterations', 'hor_step', + 'ver_start', 'ver_stop', 'ver_iterations', 'ver_step'} + + Parameters: + hor_range -> Horizontal phase offset range. + This parameter is given as a list of three keyed elements: + 'start' -> Defines the first point of the range. [-32,32]. + 'stop' -> Defines the last point of the range. [-32,32]. + 'step' -> Defines the step at which the range is iterated. [1,2,4,8]. + ver_range -> Vertical volateg offset range. + This parameter is given as a list of three keyed elements: + 'start' -> Defines the first point of the range. [-127,127]. + 'stop' -> Defines the last point of the range. [-127,127]. + 'step' -> Defines the step at which the range is iterated. [1,2,4,8]. + """ + self.log.trace("Parsing horizontal/vertical ranges...") + parsed_ranges = {} + # Do some input validation. + assert ('start' in hor_range) and ('stop' in hor_range) and ('step' in hor_range) + assert ('start' in ver_range) and ('stop' in ver_range) and ('step' in ver_range) + assert hor_range['step'] in (1, 2, 4, 8) + assert ver_range['step'] in (1, 2, 4, 8) + # Parse the horizontal and vertical ranges, and build the output lists. + parsed_ranges['hor_start'] = self.rxout_div * hor_range['start'] + parsed_ranges['hor_stop' ] = self.rxout_div * hor_range['stop' ] + parsed_ranges['hor_step' ] = self.rxout_div * hor_range['step' ] + parsed_ranges['hor_iterations'] = math.ceil( \ + (parsed_ranges['hor_stop'] - parsed_ranges['hor_start'] + 1) / \ + parsed_ranges['hor_step']) + self.log.trace("hor_start=%d hor_stop=%d hor_step=%d hor_iterations=%d", + parsed_ranges['hor_start'], parsed_ranges['hor_stop'], + parsed_ranges['hor_step' ], parsed_ranges['hor_iterations']) + parsed_ranges['ver_start'] = ver_range['start'] + parsed_ranges['ver_stop' ] = ver_range['stop'] + parsed_ranges['ver_step' ] = ver_range['step'] + parsed_ranges['ver_iterations'] = math.ceil( \ + (ver_range['stop'] - ver_range['start'] + 1) / \ + ver_range['step']) + self.log.trace("ver_start=%d ver_stop=%d ver_step=%d ver_iterations=%d", + parsed_ranges['ver_start'], parsed_ranges['ver_stop'], + parsed_ranges['ver_step' ], parsed_ranges['ver_iterations']) + # Return the list with the extracted parameters. + return parsed_ranges + + + def eyescan_config(self, + es_qualifier =[0x0000, 0x0000, 0x0000, 0x0000, 0x0000], + es_qual_mask =[0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF, 0xFFFF], + es_sdata_mask=[]): + """ + This function configures the current GT number to enable Eye Scan. + The following attributes are configured for the given transceiver lane: + - ES_QUALIFIER + - ES_QUAL_MASK + - ES_SDATA_MASK + - ES_PRESCALE + + Parameters: + es_qualifier -> This element must be a 5 elements (16-bit integers) 1D array, + containing the 80-bit ES_QUALIFIER value. + This element is optional, default values available. + es_qualifier[0] -> ES_QUALIFIER[15:0] + ... + es_qualifier[4] -> ES_QUALIFIER[79:64] + es_qual_mask -> This element must be a 5 elements (16-bit integers) 1D array, + containing the 80-bit ES_QUAL_MASK value. + This element is optional, default values available. + es_qual_mask[0] -> ES_QUAL_MASK[15:0] + ... + es_qual_mask[4] -> ES_QUAL_MASK[79:64] + es_sdata_mask -> This element must be a 5 elements (16-bit integers) 1D array, + containing the 80-bit ES_SDATA_MASK value. + If this mask is not given, then an internal default will be + assigned for the statistical eye application based on the + rx_int_datawidth global parameter value. + es_sdata_mask[0] -> ES_SDATA_MASK[15:0] + ... + es_sdata_mask[4] -> ES_SDATA_MASK[79:64] + """ + # + # [15: 0] [31:16] [47:32] [63:48] [79:64] + ES_SDATA_MASK_DICT = {16 : [0xFFFF, 0x00FF, 0xFF00, 0xFFFF, 0xFFFF], + 20 : [0xFFFF, 0x000F, 0xFF00, 0xFFFF, 0xFFFF], + 32 : [0x00FF, 0x0000, 0xFF00, 0xFFFF, 0xFFFF], + 40 : [0x0000, 0x0000, 0xFF00, 0xFFFF, 0xFFFF]} + # + # Configure each lane in the global lanes array. + for current_lane in self.lanes: + self.set_global_lane(current_lane) + self.log.trace("Configuring GT #%d...", self.lane_num) + # Do some input validation. + assert len(es_qualifier) == 5 + assert len(es_qual_mask) == 5 + if len(es_sdata_mask) != 5: + self.log.trace("ES_SDATA_MASK defined based on rx_int_datawidth=%d", + self.rx_int_datawidth) + es_sdata_mask = ES_SDATA_MASK_DICT[self.rx_int_datawidth] + # Configure the ES_QUALIFIER attribute. + self.log.trace("Configuring the ES_QUALIFIER attribute for GT #%d...", self.lane_num) + ES_QUALIFIER_FIRST_ADDR = 0x02C + ES_QUALIFIER_LAST_ADDR = 0x030 + index = 0 + for drp_addr in range(ES_QUALIFIER_FIRST_ADDR, ES_QUALIFIER_LAST_ADDR + 0x1): + self.jesdcore.drp_access(rd=False, addr=drp_addr, + wr_data=es_qualifier[index]); index += 1 + # Configure the ES_QUAL_MASK attribute. + # According to UG476 pg. 217, ES_QUAL_MASK for a statistical eye is 80 1's, + # so the sample counter and error counter accumulate on every cycle. + # Thus, we write this registers to the given GT number to configure the hardware. + self.log.trace("Configuring the ES_QUAL_MASK attribute for GT #%d...", self.lane_num) + ES_QUAL_MASK_FIRST_ADDR = 0x031 + ES_QUAL_MASK_LAST_ADDR = 0x035 + index = 0 + for drp_addr in range(ES_QUAL_MASK_FIRST_ADDR, ES_QUAL_MASK_LAST_ADDR + 0x1): + self.jesdcore.drp_access(rd=False, addr=drp_addr, + wr_data=es_qual_mask[index]); index += 1 + # Configure the ES_SDATA_MASK attribute. + self.log.trace("Configuring the ES_SDATA_MASK attribute for GT #%d...", self.lane_num) + ES_SDATA_MASK_FIRST_ADDR = 0x036 + ES_SDATA_MASK_LAST_ADDR = 0x03A + index = 0 + for drp_addr in range(ES_SDATA_MASK_FIRST_ADDR, ES_SDATA_MASK_LAST_ADDR + 0x1): + self.jesdcore.drp_access(rd=False, addr=drp_addr, + wr_data=es_sdata_mask[index]); index += 1 + # Configure the ES_PRESCALE attribute. + ES_PRESCALE_ADDR = 0x03B + self.log.trace("Configuring the ES_PRESCALE attribute for GT #%d...", self.lane_num) + drp_x03B_rb = self.jesdcore.drp_access(rd=True, addr=ES_PRESCALE_ADDR) + es_prescale = self.prescale & 0x1F + drp_x03B_wr = (drp_x03B_rb & ~0xF800) | (es_prescale << 11) + self.jesdcore.drp_access(rd=False, addr=ES_PRESCALE_ADDR, wr_data=drp_x03B_wr) + # According to UG476 pg. 220, for a GTX xcvr PMA_RSV2[5] should always be + # asserted when using Eye Scan; otherwise, the Eye Scan circuitry in the PMA + # will be powered down. + PMA_RSV2_ADDR = 0x082 + if self.MGT_TYPE == 'GTX': + self.log.trace("Asserting that PMA_RSV2[5] bit is high for GTX #%d...", self.lane_num) + drp_x082_rb = self.jesdcore.drp_access(rd=True, addr=PMA_RSV2_ADDR) + pma_rsv2_bit5 = (drp_x082_rb >> 5) & 0x1 + if not pma_rsv2_bit5: + self.log.error("PMA_RSV2[5] is not asserted for GT#{}, enable it before link bringup." + .format(self.lane_num)) + raise RuntimeError('Eye Scan cicuitry is powered down, see log for details.') + self.log.info("Configured GT #%d!", self.lane_num) + self.set_global_lane(None) + return + + + def eyescan_control(self, err_det_en=True, run=False, arm=False): + """ + Configures the eye scan control state machine for the current XCVR lane. + This function returns True if there was an update in the register map. + + Parameters: + err_det_en -> Enable error detection. + 1 -> statistical eye | 0 -> scope and waveform views. + run -> Asserting this parameter causes a state transition from the WAIT + state to the RESET state, initiating a BER measurement sequence. + arm -> Asserting this parameter causes a state transition from the WAIT + state to the RESET state, initiating a diagnostic sequence. + In the ARMED state, deasserting this bit causes a state transition + to the READ state if one of the states of bits x03D[5:2] below is + not met. + """ + ARM_TRIGGER_ON = {"error_detected" : 0b0001,\ + "qualifier_pattern": 0b0010,\ + "es_trigger" : 0b0100,\ + "immediate" : 0b1000} + EYE_SCAN_EN_VAL = 0b1 + self.log.trace("Eyescan state machine control for MGT #%d", self.lane_num) + # Read the current register values. + drp_x03d_rb = self.jesdcore.drp_access(rd=True, addr=0x03D) + # Determine the GT Channel attributes to be changed. + es_errdet_en = int(err_det_en) + es_eye_scan_en = EYE_SCAN_EN_VAL + es_control = (int(run) << 0) | \ + (int(arm) << 1) | \ + (ARM_TRIGGER_ON["error_detected"] << 2) + self.log.trace("Control attributes... ES_ERRDET_EN:0b{0:b}" + " ES_EYE_SCAN_EN:0b{1:b} ES_CONTROL:0b{2:06b}" + .format(es_errdet_en, es_eye_scan_en, es_control)) + # Build and write the new register values. + drp_x03d_wr = ((drp_x03d_rb & ~0x023F) << 0) | \ + (es_errdet_en << 9) | \ + (es_eye_scan_en << 8) | \ + (es_control << 0) + self.jesdcore.drp_access(rd=False, addr=0x03D, wr_data=drp_x03d_wr) + return drp_x03d_rb != drp_x03d_wr # Return True when the register changed. + + + def eyescan_offset(self, hor_offset=0, ver_offset=0, ut_sign='+UT'): + """ + Configures the eyescan horizontal phase offset and vertical voltage offset + for the current XCVR lane number. + This function returns true if at least one register was updated. + + Parameters: + hor_offset -> Horizontal phase offset. + [-32, 32] corresponding to -0.5 UI to +0.5 UI. + ver_offset -> Vertical voltage offset. + [-127, 127] corresponding to 0.39% increments. + ut_sign -> UT tap sign: '+UT' or '-UT'. + """ + UT_SIGN_BIT = {'+UT': 0b0, '-UT': 0b1} + self.log.trace("Offset configuration for MGT #{}:".format(self.lane_num)) + # Do some input validation for the given parameters. + assert ut_sign.upper() in ('+UT', '-UT') + self.log.trace("GT #%d Horizontal offset: %d Vertical offset: %d Tap: %s", + self.lane_num, hor_offset, ver_offset, ut_sign) + # Read the current register values. + drp_x03b_rb = self.jesdcore.drp_access(rd=True, addr=0x03B) + drp_x03c_rb = self.jesdcore.drp_access(rd=True, addr=0x03C) + # Determine the GT channel attributes to be changed. + es_vert_offset = ((abs(ver_offset) & 0x007F) << 0) | \ + ( int(ver_offset < 0) << 7) | \ + ( UT_SIGN_BIT[ut_sign] << 8) + es_horz_offset = (hor_offset & 0x0FFF) + self.log.trace("Offset attributes... ES_HORZ_OFFSET:0b{0:012b} ES_VERT_OFFSET:0b{1:09b}" + .format(es_horz_offset, es_vert_offset)) + # Build and write new register values. + drp_x03b_wr = (drp_x03b_rb & ~0x01FF) | (es_vert_offset & 0x01FF) + drp_x03c_wr = (drp_x03c_rb & ~0x0FFF) | (es_horz_offset & 0x0FFF) + self.jesdcore.drp_access(rd=False, addr=0x03B, wr_data=drp_x03b_wr) + self.jesdcore.drp_access(rd=False, addr=0x03C, wr_data=drp_x03c_wr) + # Return True when at least one of the two registers changed. + return (drp_x03b_rb != drp_x03b_wr) or (drp_x03c_rb != drp_x03c_wr) + + + def eyescan_wait(self, wait_for='END', exit_after=10000): + """ + This function waits for the eye scan control FSM of the current lane + number, to transition to the given state (wait_for). + Returns True when the desired state is reached. + + Parameters: + wait_for -> State which the function waits the FSM to transition to. + {'WAIT','RESET','COUNT','END','ARMED','READ'} + """ + STATE_DECODE = {'WAIT': 0b000, 'RESET': 0b001, 'COUNT': 0b011, \ + 'END' : 0b010, 'ARMED': 0b101, 'READ' : 0b100} + self.log.trace("Waiting for %s state at MGT #%d", wait_for, self.lane_num) + # Validate the state input parameter. + assert wait_for.upper() in ('WAIT', 'RESET', 'COUNT', 'END', 'ARMED', 'READ') + # Poll the es_control_status GT attribute until the FSM transistions to + # the given state. + state_reached = False + iterations = 0 + delay = 2 ** (self.prescale - 13) if (self.prescale > 13) else 0 + while not state_reached: + # Read the status register. + es_control_status = self.jesdcore.drp_access(rd=True, addr=0x151) + done = es_control_status & 0x0001 + current_state = (es_control_status & 0x000E) >> 1 + self.log.trace("Current state: 0b{0:03b} Status: %s" + .format(current_state), {0b0:'Not Done!', 0b1: 'Done!'}[done]) + # Compare current state with expected state. + state_reached = (current_state == STATE_DECODE[wait_for]) + if (iterations >= 100) and (not state_reached) and (iterations % 100 == 0): + self.log.debug("%s state has not been reached for GT #%d after %d iterations.", + wait_for, self.lane_num, iterations) + time.sleep(delay / 1000.0) + # Exit after so many iterations, prevneting the application to hang. + iterations += 1 + if exit_after == iterations: + break + # Validate that the expected state was reached. + if not state_reached: + self.log.error("%s state was not reached at GT #%d after %d polls.", + wait_for, self.lane_num, iterations) + raise Exception("Eyescan status timed out, see log for details.") + self.log.trace("%s state reached at GT #%d", wait_for, self.lane_num) + return state_reached + + + def eyescan_counters(self): + """ + This function reads the error and sample counters for the current lane number. + Returns a tuple with the error and sample count. + """ + self.log.trace("Reading counters for GT #%d ...", self.lane_num) + counters = {'error_count': 0x0000, 'sample_count': 0x0000} + # Read the error counter. + counters['error_count' ] = self.jesdcore.drp_access(rd=True, addr=0x14F) & 0xFFFF + counters['sample_count'] = self.jesdcore.drp_access(rd=True, addr=0x150) & 0xFFFF + self.log.trace("es_error_count: 0x{:04X} es_sample_count: 0x{:04X}" + .format(counters['error_count'], counters['sample_count'])) + return counters + + + def eyescan_acquisition(self, hor_offset=0, ver_offset=0): + """ + This function performs an acquisition for each lane in the lanes global array. + Each GT is tested at the same "coordinate". Only after all GTs measurements + are completed, the function returns. + + Parameters: + hor_offset -> Horizontal phase offset. + [-32, 32] corresponding to -0.5 UI to +0.5 UI. + ver_offset -> Vertical voltage offset. + [-127, 127] corresponding to 0.39% increments. + """ + self.log.trace("Starting acquisition for GTs {}".format(self.lanes)) + acq_counters = [] # Array that stores multiple sl_counters lists. + for _ in range(0, max(self.lanes) + 1): + acq_counters.append({}) + # + # First eye scan measurement (LPM | DFE) + # Start the FSM on all the requested lanes. + for current_lane in self.lanes: + self.set_global_lane(current_lane) + self.log.trace("Starting +UT acquisition for GT #%d", self.lane_num) + # Clear run & arm bits in the Eyescan control. + self.eyescan_control(err_det_en=True, run=False, arm=False) + # Set offsets with +UT. + self.eyescan_offset(hor_offset, ver_offset, ut_sign='+UT') + # Start eyescan FSM: set run with ErrDet enabled. + self.eyescan_control(err_det_en=True, run=True, arm=False) + # + # Wait for the FSM to complete on each lane, read counters, and + # start second eye scan measurement (DFE eq. only). + for current_lane in self.lanes: + self.set_global_lane(current_lane) + # Wait for END state. + self.eyescan_wait(wait_for='END') + # Clear run & arm bits in the Eyescan control. + self.eyescan_control(err_det_en=True, run=False, arm=False) + # Read counters with +UT. + acq_counters[self.lane_num]['+UT'] = self.eyescan_counters() + self.log.trace("Results +UT GT #%d... Errors=%d Samples=%d.", self.lane_num, + acq_counters[self.lane_num]['+UT']['error_count'], + acq_counters[self.lane_num]['+UT']['sample_count']) + # Start second eye scan measurement (DFE eq. only). + if self.eq_mode == 'DFE': + # Set offsets with -UT. + self.eyescan_offset(hor_offset, ver_offset, ut_sign='-UT') + # Start eyescan FSM: set run with ErrDet enabled. + self.eyescan_control(err_det_en=True, run=True, arm=False) + else: + self.log.debug("Single measurement finalized for GT #%d (H=%d, V=%d, %s).", + self.lane_num, hor_offset, ver_offset, self.eq_mode) + # + # Wait for the FSM (-UT, DFE only) to complete on each lane, and read counters. + if self.eq_mode == 'DFE': + for current_lane in self.lanes: + self.set_global_lane(current_lane) + # Wait for END state. + self.eyescan_wait(wait_for='END') + # Clear run & arm bits in the Eyescan control. + self.eyescan_control(err_det_en=True, run=False, arm=False) + # Read counters with -UT. + acq_counters[self.lane_num]['-UT'] = self.eyescan_counters() + self.log.trace("Results -UT GT #%d... Errors=%d Samples=%d.", self.lane_num, + acq_counters[self.lane_num]['-UT']['error_count'], + acq_counters[self.lane_num]['-UT']['sample_count']) + self.log.debug("Single measurement finalized for GT #%d (H=%d, V=%d, %s).", + self.lane_num, hor_offset, ver_offset, self.eq_mode) + # + self.set_global_lane(None) + # Return the error and sample counters for all lanes, both +UT and -UT. + return acq_counters + + + def eyescan_sweep(self, bin_file, parsed_ranges): + """ + Performs Eye Scan "measurement loop" (error counting) acquisitions across the + given phase and voltage offset ranges. + + This function creates a binary file containing the sweep results. + The binary file is a set of bytes, where file[position] represents a byte + (8-bit) at the given position. The bytes are saved as follows: + + If eq_mode = 'LPM'... + file[offset + 4*lanes*i + 4*curr_lane + 0] = sample_count[15:0] (+UT) (ith acquisition) + file[offset + 4*lanes*i + 4*curr_lane + 2] = error_count[15:0] (+UT) (ith acquisition) + + If eq_mode = 'DFE'... + file[offset + 4*lanes*(i*2 + 0) + 4*curr_lane + 0] = sample_count[15:0] (+UT) (ith acquisition) + file[offset + 4*lanes*(i*2 + 0) + 4*curr_lane + 2] = error_count[15:0] (+UT) (ith acquisition) + file[offset + 4*lanes*(i*2 + 1) + 4*curr_lane + 0] = sample_count[15:0] (-UT) (ith acquisition) + file[offset + 4*lanes*(i*2 + 1) + 4*curr_lane + 2] = error_count[15:0] (-UT) (ith acquisition) + + Where, + i -> single acquisition iteration number, ranging from 0 to + (hor_iterations * ver_iterations - 1). + offset -> set offset for metadata to be stored at the beginning of + the binary file. + lanes -> total number of lanes to be scanned. Defined as len(self.lanes). + curr_lane -> a given lane number. It should be any value in the lanes array. + + Parameters: + bin_file -> Binary file reference to write data to. Passed from top level function. + parsed_ranges -> This is a keyed list with parsed parameters from parse_ranges(). + """ + def write_byte_counters(acq_counters): + """ + This method writes the acquisition counters for each lane to the binary file. + """ + # Write the sample and error counters for all given lanes. + for current_lane in self.lanes: + # Write the counters for the current lane. + sl_counters = acq_counters[current_lane] + self.log.debug("Writing +UT counters for GT #{0}: {1}" + .format(current_lane, sl_counters)) + byte_number = (sl_counters['+UT']['sample_count']).to_bytes(2, 'little') + bin_file.write(byte_number) + byte_number = (sl_counters['+UT']['error_count' ]).to_bytes(2, 'little') + bin_file.write(byte_number) + # -UT results only exists when DFE eq. mode is used. + if '-UT' in sl_counters: + self.log.debug("Writing -UT counters for GT #%d...", current_lane) + byte_number = (sl_counters['-UT']['sample_count']).to_bytes(2, 'little') + bin_file.write(byte_number) + byte_number = (sl_counters['-UT']['error_count' ]).to_bytes(2, 'little') + bin_file.write(byte_number) + # + gts_string = "GTs {}".format(self.lanes) + self.log.trace("Starting sweep for %s ...", gts_string) + # Perform the Eye Scan sweep! + acq_counters = [] + total_iterations = parsed_ranges['hor_iterations'] * parsed_ranges['ver_iterations'] + iterations = 0 + # Outer loop iterates horizontally. + for hor_offset in range(parsed_ranges['hor_start'], parsed_ranges['hor_stop'] + 1, + parsed_ranges['hor_step']): + # Inner loop iterates vertically. + for ver_offset in range(parsed_ranges['ver_start'], parsed_ranges['ver_stop'] + 1, + parsed_ranges['ver_step']): + # Perform a single acquisition at each "coordinate". + acq_counters = self.eyescan_acquisition(hor_offset, ver_offset) + # Write the data to a binary file. + write_byte_counters(acq_counters) + # Report Eye Scan progress. + iterations += 1 + progress = iterations / total_iterations * 100 + # Only print status messages every PRINT_STATUS_EVERY iterations. + if iterations % self.PRINT_STATUS_EVERY == 0: + self.log.info("Eye Scan progress for %s sweep: %.2f %%", gts_string, progress) + + + def create_pes_file(self, hor_range, ver_range): + """ + This function creates a .pes file and writes the metadata header. + The file object is returned. + + 0x00 -> 0x0F : "PythonEyeScanXpY" [16 bytes] (X -> Major, Y -> Minor) + --- Data offset --- + 0x10 -> 0x11 : data_offset [ 2 bytes] + --- Eye Scan run configuration --- + 0x12 -> 0x13 : prescale [ 2 bytes] + 0x14 -> 0x15 : rxout_div [ 2 bytes] + 0x16 -> 0x17 : rx_int_datawidth [ 2 bytes] + 0x18 -> 0x19 : eq_mode [ 2 bytes] (0 -> LPM / 1 -> DFE) + --- Phase ranges --- + 0x1A -> 0x1B : hor_start [ 2 bytes] + 0x1C -> 0x1D : hor_stop [ 2 bytes] + 0x1E -> 0x1F : hor_step [ 2 bytes] + 0x20 -> 0x21 : ver_start [ 2 bytes] + 0x22 -> 0x23 : ver_stop [ 2 bytes] + 0x24 -> 0x25 : ver_step [ 2 bytes] + --- Lane(s) information --- + 0x26 -> 0x27 : number of lanes [ 2 bytes] + 0x28 -> 0x29 : lane_num array [ 2 bytes] (Each nibble represents a lane) + """ + def build_file_name(): + """ + This function builds the file name, which contains the scanned GTs and the + prescale value used. + """ + file_name = "eyescan" + # Include a time stamp. + now = datetime.datetime.now() + file_name += ("_%04d%02d%02d%02d%02d" % + (now.year, now.month, now.day, now.hour, now.minute)) + # Include the scanned slot. + file_name += ("_slot%d" % self.slot_idx) + # Include the scanned GTs. + file_name += "_gt" + for lane in self.lanes: + file_name += ("%d" % lane) + # Include the prescale value. + file_name += ("_pre%d" % self.prescale) + # Include extension. + file_name += ".pes" + return file_name + # + def write_byte_number(number=0, size=2, offset=None): + """ + This function writes a number as bytes in the binary file. + When an offset is given, the data is written at that address, leaving the + pointer there. + """ + if offset: + pes_file.seek(offset) + byte_number = (number).to_bytes(size, 'little', signed=True) + pes_file.write(byte_number) + # + # Create the directory to save the pes files if it does not exist. + if not os.path.isdir(self.SAVE_DIR): + self.log.trace("Creating directory: {}".format(self.SAVE_DIR)) + os.makedirs(self.SAVE_DIR) + # Open the binary file which data will be saved to. + file_name = build_file_name() + pes_file = open(self.SAVE_DIR + file_name, "wb+") + # Write the metadata header. + byte_string = ("PythonEyeScan"+self.VER_MAJOR+"p"+self.VER_MINOR).encode('utf-8') + pes_file.write(byte_string) # 0x00: signature string. + write_byte_number(number=0x0000) # 0x10: data_offset (placeholder). + write_byte_number(number=self.prescale) # 0x12: prescale. + write_byte_number(number=self.rxout_div) # 0x14: rxout_div. + write_byte_number(number=self.rx_int_datawidth) # 0x16: rx_int_datawidth. + write_byte_number(number={'LPM':0, 'DFE':1}[self.eq_mode]) # 0x18: eq_mode. + write_byte_number(number=hor_range['start']) # 0x1A: hor_start. + write_byte_number(number=hor_range['stop']) # 0x1C: hor_stop. + write_byte_number(number=hor_range['step']) # 0x1E: hor_step. + write_byte_number(number=ver_range['start']) # 0x20: ver_start. + write_byte_number(number=ver_range['stop']) # 0x22: ver_stop. + write_byte_number(number=ver_range['step']) # 0x24: ver_step. + write_byte_number(number=len(self.lanes)) # 0x26: number of lanes. + nibble = 0x0000 + for lane_index in range(0, len(self.lanes)): + nibble |= (self.lanes[lane_index] & 0xF) << lane_index*4 + write_byte_number(number=nibble) # 0x28: lane_num array. + # Write data offset and set pointer ready for data writing. + data_offset = pes_file.tell() + write_byte_number(number=data_offset, offset=0x10) + pes_file.seek(data_offset) + # Return the opened file. + return (file_name, pes_file) + + + def eyescan_full_scan(self, + scan_lanes=[0], + hor_range={'start':-32 , 'stop':32 , 'step': 1}, + ver_range={'start':-127, 'stop':127, 'step': 2}): + """ + This function performs all the GT configuration and starts the eye scan sweep. + The binary file should be open here. + + Parameters: + scan_lanes -> Array that represents which GTs will be scanned. The maximum size + of the array is 4, and the valid values for each item are 0,1,2,3. + hor_range -> Horizontal phase offset range. + This parameter is given as a list of three keyed elements: + 'start' -> Defines the first point of the range. [-32,32]. + 'stop' -> Defines the last point of the range. [-32,32]. + 'step' -> Defines the step at which the range is iterated. [1,2,4,8]. + ver_range -> Vertical volateg offset range. + This parameter is given as a list of three keyed elements: + 'start' -> Defines the first point of the range. [-127,127]. + 'stop' -> Defines the last point of the range. [-127,127]. + 'step' -> Defines the step at which the range is iterated. [1,2,4,8]. + """ + # Set the global lanes variable that defines which lanes will be scanned. + self.lanes = scan_lanes + # Extract the needed parameters from the given ranges. + parsed_ranges = self.parse_ranges(hor_range, ver_range) + # Create the .pes binary file. + file_name, pes_file = self.create_pes_file(hor_range, ver_range) + # Configure the requested lanes. + self.eyescan_config() + # Perform the sweep on the requested lanes. + self.eyescan_sweep(pes_file, parsed_ranges) + # Close the binary file. + pes_file.close() + return file_name diff --git a/mpm/python/usrp_mpm/cores/nijesdcore.py b/mpm/python/usrp_mpm/cores/nijesdcore.py index 90b45430f..a63da8bc1 100644 --- a/mpm/python/usrp_mpm/cores/nijesdcore.py +++ b/mpm/python/usrp_mpm/cores/nijesdcore.py @@ -61,7 +61,8 @@ class NIJESDCore(object): "tx_sysref_delay" : 10, # Cycles of delay added to TX SYSREF "tx_driver_swing" : 0b1111, # See UG476, TXDIFFCTRL "tx_precursor" : 0b00000, # See UG476, TXPRECURSOR - "tx_postcursor" : 0b00000} # See UG476, TXPOSTCURSOR + "tx_postcursor" : 0b00000, # See UG476, TXPOSTCURSOR + "enable_rx_eyescan" : False} # Enable the PMA Eye Scan circuitry. def __init__(self, regs, slot_idx=0, **kwargs): self.regs = regs @@ -210,6 +211,7 @@ class NIJESDCore(object): Initializes the core. Must happen after the reference clock is stable. """ self.log.trace("Initializing JESD204B FPGA core(s)...") + self._gt_pma_eyescan(self.enable_rx_eyescan) self._gt_pll_power_control(self.qplls_used, self.cplls_used) self._gt_reset('tx', reset_only=True) self._gt_reset('rx', reset_only=True) @@ -326,6 +328,21 @@ class NIJESDCore(object): raise RuntimeError("One or more GT QPLLs failed to lock!") self.log.trace("QPLL(s) reporting locked!") + def _gt_pma_eyescan(self, enable=False): + # According to UG476 pg. 220, for a GTX xcvr PMA_RSV2[5] should always be + # asserted when using Eye Scan; otherwise, the Eye Scan circuitry in the PMA + # will be powered down. + PMA_RSV2_DRP_ADDR = 0x082 + self.log.debug("{} the eye scan circuitry in the PMA for the GTXs..." + .format({True: "Enabling", False: "Disabling"}[enable])) + for gt_num in range(0, self.rx_lanes): + self.set_drp_target('mgt', gt_num) + drp_x082_rb = self.drp_access(rd=True, addr=PMA_RSV2_DRP_ADDR) + pma_rsv2_bit5 = int(enable) + drp_x082_wr = (drp_x082_rb & ~(0b1 << 5)) | (pma_rsv2_bit5 << 5) + self.drp_access(rd=False, addr=PMA_RSV2_DRP_ADDR, wr_data=drp_x082_wr) + self.disable_drp_target() + def set_drp_target(self, mgt_or_qpll, dev_num): """ Sets up access to the specified MGT or QPLL. This must be called @@ -382,4 +399,3 @@ class NIJESDCore(object): self.log.error("DRP read after write failed to match!") return rd_data - |