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 [ "<common options>" ] " <link port> " [ "<link options>" "] [" "<link port> " [ "<link options>" ] " ..." ]
   8 .br
   9 .B pcilmr --full
  10 .RI [ "<common 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 .B pcilmr
  68 requires root privileges (to access Extended Configuration Space), but during our testing
  69 there were no problems with the devices and they successfully returned to their normal initial
  70 state after the end of testing.
  71
  72 .SH RESULTS GRADING
  73 The PCIe specification provides reference values for the eye diagram, which are also used by the
  74 .B pcilmr
  75 to evaluate the results, but it seems that it makes sense to contact the
  76 manufacturer of a particular device for references.
  77
  78 The utility uses values set in PCIe Base Spec Rev. 5.0 Section 8.4.2 as the default eye width and height
  79 minimum references. Recommended values were taken from
  80 the PCIe Architecture PHY Test Spec Rev 5.0 (Transmitter Electrical Compliance).
  81
  82 Reference grading values currently used by the utility are presented in the table below:
  83
  84 .TS
  85 box tab(:);
  86 C | Cb S | Cb S
  87 C | Cb | Cb | Cb | Cb
  88 Lb | C | C | C | C.
  89 \&:16 GT/s (Gen 4):32 GT/s (Gen 5)
  90 \&:EW:EH:EW:EH
  91 _
  92 Min:T{
  93 18.75 ps
  94 .br
  95 30% UI
  96 T}:15 mV:T{
  97 9.375 ps
  98 .br
  99 30% UI
 100 T}:15 mV
 101 _
 102 Rec:T{
 103 23.75 ps
 104 .br
 105 38% UI
 106 T}:21 mV:T{
 107 10.157 ps
 108 .br
 109 33% UI
 110 T}:19.75 mV
 111 .TE
 112
 113 .B pcilmr
 114 uses full eye width and height values to grade lanes. However, it is possible that
 115 device supports only one side margining. In such cases by default utility will
 116 calculate EW or EH as a double one side result.
 117
 118 If info for specific device is available, you can configure grading criteria
 119 and tweak utility behavior in one-side only cases for your device using
 120 .I -g
 121 link specific option (see below).
 122
 123 .SH HARDWARE QUIRKS SUPPORT
 124
 125 Thanks to testing or directly from the manufacturer's documentation, we know that
 126 some devices require special treatment during the margining.
 127 Utility detects such devices based on their Vendor ID - Device ID pair.
 128 Right now the list of special devices is hardcoded in
 129 .I margin_hw
 130 file. For such devices utility can automatically adjust port margining parameters
 131 or grading options.
 132
 133 For example, for Ice Lake CPUs RC ports
 134 .B pcilmr
 135 will change device MaxVoltageOffset value and will force the use of
 136 .RI ' "one side is the whole" "' grading mode."
 137
 138 .SH OPTIONS
 139 .SS Device Specifier
 140 .B "You can specify Downstream or Upstream Port of the Link."
 141 .TP
 142 .B "<device/component>" \t
 143 .RI [ "<domain>" :] <bus> : <dev> . <func>
 144 (see
 145 .BR lspci (8))
 146 .SS Utility Modes
 147 .TP
 148 .BI --margin " <downstream component> ..."
 149 Margin selected Links.
 150 .TP
 151 .B --full
 152 Margin all ready for testing (in a meaning similar to the
 153 .B --scan
 154 option) Links in the system (one by one).
 155 .TP
 156 .B --scan
 157 Scan for Links with negotiated speed 16 GT/s or higher. Mark "Ready" those of them
 158 in which at least one of the Link sides have Margining Ready bit set meaning that
 159 these Links are ready for testing and you can run utility on them.
 160 .SS Margining Common (for all specified links) options
 161 .B -c
 162 Print Device Lane Margining Capabilities only. Do not run margining.
 163 .TP
 164 .BI -e " <errors>"
 165 Specify Error Count Limit for margining.
 166 .br
 167 Default: 4.
 168 .TP
 169 .BI -o " <directory>"
 170 Save margining results in csv form into the specified directory. Utility
 171 will generate file with the name in form of
 172 .RI "\[dq]lmr_" "<port>" "_Rx" # _ <timestamp> ".csv\[dq]"
 173 for each successfully tested receiver.
 174 .TP
 175 .BI -d " <time>"
 176 Specify dwell time in seconds for the margining step.
 177 .br
 178 Default: 1 s
 179 .SS Margining Link specific options
 180 .TP
 181 \fB\-l\fI <lane>\fP[\fI,<lane>...\fP]
 182 .R Specify lanes for margining.
 183 .br
 184 Remember that Device may use Lane Reversal for Lane numbering. However, utility
 185 uses logical lane numbers in arguments and for logging. Utility will automatically
 186 determine Lane Reversal and tune its calls.
 187 .br
 188 Default: all link lanes.
 189 .TP
 190 \fB-r\fI <recvn>\fP[\fI,<recvn>...\fP]
 191 Specify Receivers to select margining targets.
 192 .br
 193 Default: all available Receivers (including Retimers).
 194 .TP
 195 .BI -p " <parallel_lanes>"
 196 Specify number of lanes to margin simultaneously.
 197 .br
 198 According to spec it's possible for Receiver to margin up to MaxLanes + 1
 199 lanes simultaneously, but during testing, performing margining on several
 200 lanes simultaneously led to results that were different from sequential
 201 margining, so this feature requires additional verification and
 202 .I -p
 203 option right now is for experiments mostly.
 204 .br
 205 Default: 1.
 206 .PP
 207 .B "Use only one of -T/-t options at the same time (same for -V/-v)."
 208 .br
 209 .B "Without these options utility will use MaxSteps from Device"
 210 .B "capabilities as test limit."
 211 .TP
 212 .B -T
 213 Time Margining will continue until the Error Count is no more
 214 than an Error Count Limit. Use this option to find Link limit.
 215 .TP
 216 .BI -t " <steps>"
 217 Specify maximum number of steps for Time Margining.
 218 .TP
 219 .B -V
 220 Same as
 221 .I -T
 222 option, but for Voltage.
 223 .TP
 224 .BI -v " <steps>"
 225 Specify maximum number of steps for Voltage Margining.
 226 .TP
 227 \fB-g\fI <recvn>\fPt=\fI<criteria>\fP{%|ps}[,f]
 228 .TP
 229 .IB "   <recvn>" t=f[, "<criteria>" "{%|ps}]"
 230 .TP
 231 .IB "   <recvn>" v= "<criteria>" "[,f]"
 232 .TP
 233 .IB "   <recvn>" v=f[, "<criteria>" ]
 234 Specify pass/fail grading criteria for eye width (timing - t) or height
 235 (voltage - v) for one of the link receivers. For EW you must choose one of the
 236 units (% UI or ps), for EH mV is used.
 237 .br
 238 Additional flag
 239 .I f
 240 is for situations when port doesn't support two side independent
 241 margining. In such cases by default utility will calculate EW or EH as a
 242 double one side result. You can add
 243 .I f
 244 flag for
 245 .I -g
 246 option to tell the utility that the result in one direction is actually the
 247 measurement of the full eye and it does not need to be multiplied. This is so called
 248 .RI ' "one side is the whole" "' grading mode."
 249
 250 .SH EXAMPLES
 251 Utility syntax example:
 252 .RS
 253 .BI "pcilmr -o " "csv ab:0.0 " "-r " "1,6 " "-g " "1t=20% " "-g " "1v=f,30 52:0.0 " "-l " "0,1,2 " "-TV"
 254 .RE
 255
 256 .UR https://gist.github.com/bombanya/f2b15263712757ffba1a11eea011c419
 257 Examples of collected results on different systems.
 258 .UE
 259
 260 .SH SEE ALSO
 261 .nh
 262 .BR lspci (8),
 263 .B PCI Express Base Specification (Lane Margining at Receiver)
 264 .hy