Debian Codegraph @

upstream/debian-unstable/man8/pcilmr.8

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