pcilmr.man

   1 .TH PCILMR 8 "@TODAY@" "@VERSION@" "The PCI Utilities"
   2 .SH NAME
   3 pcilmr \- margin PCIe Links
   4 .SH SYNOPSIS
   5 .B pcilmr
   6 .RB [ "--margin" ]
   7 .RI [ "<margining options>" ] " <downstream component> ..."
   8 .br
   9 .B pcilmr --full
  10 .RI [ "<margining options>" ]
  11 .br
  12 .B pcilmr --scan
  13 .SH CONFIGURATION
  14 List of the requirements for links and system settings
  15 to run the margining test.
  16
  17 .B BIOS settings
  18 (depends on the system, relevant for server baseboards
  19 with Xeon CPUs):
  20 .IP \[bu] 3
  21 Turn off PCIe Leaky Bucket Feature, Re-Equalization and Link Degradation;
  22 .IP \[bu]
  23 Set Error Thresholds to 0;
  24 .IP \[bu]
  25 Intel VMD for NVMe SSDs - in case of strange behavior of the
  26 .BR pcilmr,
  27 try to run it with the VMD turned off.
  28 .PP
  29 .B Device (link) requirements:
  30 .IP
  31 .I "Configured by the user before running the utility, the utility does not change them:"
  32 .RS
  33 .IP \[bu] 3
  34 The current Link data rate must be 16.0 GT/s or higher (right now
  35 utility supports 16 GT/s and 32 GT/s Links);
  36 .IP \[bu]
  37 Link Downstream Component must be at D0 Power Management State.
  38 .RE
  39 .IP
  40 .I "Configured by the utility during operation, utility set them to their original "
  41 .I "state after receiving the results:"
  42 .RS
  43 .IP \[bu] 3
  44 The ASPM must be disabled in both the Downstream Port and Upstream Port;
  45 .IP \[bu]
  46 The Hardware Autonomous Speed Disable bit of the Link Control 2 register must be Set in both the
  47 Downstream Port and Upstream Port;
  48 .IP \[bu]
  49 The Hardware Autonomous Width Disable bit of the Link Control register must be Set in both the
  50 Downstream Port and Upstream Port.
  51 .SH DESCRIPTION
  52 .B pcilmr
  53 utility allows you to take advantage of the PCIe Lane Margining at the Receiver
  54 capability which is mandatory for all Ports supporting a data rate of 16.0 GT/s or
  55 higher, including Pseudo Ports (Retimers). Lane Margining at Receiver enables system
  56 software to obtain the margin information of a given Receiver while the Link is in the
  57 L0 state. The margin information includes both voltage and time, in either direction from
  58 the current Receiver position. Margining support for timing is required, while support
  59 for voltage is optional at 16.0 GT/s and required at 32.0 GT/s and higher data rates. Also,
  60 independent time margining and independent voltage margining is optional.
  61
  62 Utility allows to get an approximation of the eye margin diagram in the form of a rhombus
  63 (by four points). Lane Margining at the Receiver capability enables users to margin PCIe
  64 links without a hardware debugger and without the need to stop the target system. Utility
  65 can be useful to debug link issues due to receiver margins.
  66
  67 However, the utility results may be not particularly accurate and, as it was found out during
  68 testing, specific devices provide rather dubious capability support and the reliability of
  69 the information they provide is questionable. The PCIe specification provides reference values
  70 for the eye diagram, which are also used by the
  71 .B pcilmr
  72 to evaluate the results, but it seems that it makes sense to contact the
  73 manufacturer of a particular device for references.
  74
  75 The PCIe Base Specification Revision 5.0 sets allowed range for Timing Margin from 20%\~UI to 50%\~UI and
  76 for Voltage Margin from 50\~mV to 500\~mV. Utility uses 30%\~UI as the recommended
  77 value for Timing - taken from NVIDIA presentation ("PCIe 4.0 Mass Electrical Margins Data
  78 Collection").
  79
  80 .B pcilmr
  81 requires root privileges (to access Extended Configuration Space), but during our testing
  82 there were no problems with the devices and they successfully returned to their normal initial
  83 state after the end of testing.
  84
  85 .SH OPTIONS
  86 .SS Device Specifier
  87 .B "<device/component>" \t
  88 .RI [ "<domain>" :] <bus> : <dev> . <func>
  89 (see
  90 .BR lspci (8))
  91 .SS Utility Modes
  92 .TP
  93 .BI --margin " <downstream component> ..."
  94 Margin selected Links.
  95 .TP
  96 .B --full
  97 Margin all ready for testing (in a meaning similar to the
  98 .B --scan
  99 option) Links in the system (one by one).
 100 .TP
 101 .B --scan
 102 Scan for Links with negotiated speed 16 GT/s or higher. Mark "Ready" those of them
 103 in which at least one of the Link sides have Margining Ready bit set meaning that
 104 these Links are ready for testing and you can run utility on them.
 105 .SS Margining Test options
 106 .TP
 107 .B -c
 108 Print Device Lane Margining Capabilities only. Do not run margining.
 109 .TP
 110 \fB\-l\fI <lane>\fP[\fI,<lane>...\fP]
 111 Specify lanes for margining.
 112 .br
 113 Remember that Device may use Lane Reversal for Lane numbering. However, utility
 114 uses logical lane numbers in arguments and for logging. Utility will automatically
 115 determine Lane Reversal and tune its calls.
 116 .br
 117 Default: all link lanes.
 118 .TP
 119 .BI -e " <errors>"
 120 Specify Error Count Limit for margining.
 121 .br
 122 Default: 4.
 123 .TP
 124 \fB-r\fI <recvn>\fP[\fI,<recvn>...\fP]
 125 Specify Receivers to select margining targets.
 126 .br
 127 Default: all available Receivers (including Retimers).
 128 .TP
 129 .BI -p " <parallel_lanes>"
 130 Specify number of lanes to margin simultaneously.
 131 .br
 132 According to spec it's possible for Receiver to margin up to MaxLanes + 1
 133 lanes simultaneously, but during testing, performing margining on several
 134 lanes simultaneously led to results that were different from sequential
 135 margining, so this feature requires additional verification and
 136 .I -p
 137 option right now is for experiments mostly.
 138 .br
 139 Default: 1.
 140 .PP
 141 .B "Use only one of -T/-t options at the same time (same for -V/-v)."
 142 .br
 143 .B "Without these options utility will use MaxSteps from Device"
 144 .B "capabilities as test limit."
 145 .TP
 146 .B -T
 147 Time Margining will continue until the Error Count is no more
 148 than an Error Count Limit. Use this option to find Link limit.
 149 .TP
 150 .BI -t " <steps>"
 151 Specify maximum number of steps for Time Margining.
 152 .TP
 153 .B -V
 154 Same as
 155 .I -T
 156 option, but for Voltage.
 157 .TP
 158 .BI -v " <steps>"
 159 Specify maximum number of steps for Voltage Margining.
 160 .SS Margining Log options
 161 .TP
 162 .BI -o " <directory>"
 163 Save margining results in csv form into the specified directory. Utility
 164 will generate file with the name in form of
 165 .RI "\[dq]lmr_" "<downstream component>" "_Rx" # _ <timestamp> ".csv\[dq]"
 166 for each successfully tested receiver.
 167
 168 .SH EXAMPLES
 169 Utility syntax example:
 170 .RS
 171 .BI "pcilmr -l" " 0,1 " "-r" " 1,6 " "-TV" " ab:0.0 52:0.0"
 172 .RE
 173
 174 .UR https://gist.github.com/bombanya/f2b15263712757ffba1a11eea011c419
 175 Examples of collected results on different systems.
 176 .UE
 177
 178 .SH SEE ALSO
 179 .nh
 180 .BR lspci (8),
 181 .B PCI Express Base Specification (Lane Margining at Receiver)
 182 .hy