PCILMR(8) The PCI Utilities PCILMR(8)
NAME
pcilmr - margin PCIe Links
SYNOPSIS
pcilmr [--margin] [] [] [ [] ...]
pcilmr --full []
pcilmr --scan
CONFIGURATION
List of the requirements for links and system settings to run the margining test.
BIOS settings (depends on the system, relevant for server baseboards with Xeon CPUs):
• Turn off PCIe Leaky Bucket Feature, Re-Equalization and Link Degradation;
• Set Error Thresholds to 0;
• Intel VMD for NVMe SSDs - in case of strange behavior of the pcilmr, try to run it with the VMD turned off.
Device (link) requirements:
Configured by the user before running the utility, the utility does not change them:
• The current Link data rate must be 16.0 GT/s or higher (right now utility supports 16 GT/s and 32 GT/s
Links);
• Link Downstream Component must be at D0 Power Management State.
Configured by the utility during operation, utility set them to their original state after receiving the re‐
sults:
• The ASPM must be disabled in both the Downstream Port and Upstream Port;
• The Hardware Autonomous Speed Disable bit of the Link Control 2 register must be Set in both the Downstream
Port and Upstream Port;
• The Hardware Autonomous Width Disable bit of the Link Control register must be Set in both the Downstream
Port and Upstream Port.
DESCRIPTION
pcilmr utility allows you to take advantage of the PCIe Lane Margining at the Receiver capability which is mandatory
for all Ports supporting a data rate of 16.0 GT/s or higher, including Pseudo Ports (Retimers). Lane Margining at Re‐
ceiver enables system software to obtain the margin information of a given Receiver while the Link is in the L0
state. The margin information includes both voltage and time, in either direction from the current Receiver position.
Margining support for timing is required, while support for voltage is optional at 16.0 GT/s and required at 32.0
GT/s and higher data rates. Also, independent time margining and independent voltage margining is optional.
Utility allows to get an approximation of the eye margin diagram in the form of a rhombus (by four points). Lane Mar‐
gining at the Receiver capability enables users to margin PCIe links without a hardware debugger and without the need
to stop the target system. Utility can be useful to debug link issues due to receiver margins.
pcilmr requires root privileges (to access Extended Configuration Space), but during our testing there were no prob‐
lems with the devices and they successfully returned to their normal initial state after the end of testing.
RESULTS GRADING
The PCIe specification provides reference values for the eye diagram, which are also used by the pcilmr to evaluate
the results, but it seems that it makes sense to contact the manufacturer of a particular device for references.
The utility uses values set in PCIe Base Spec Rev. 5.0 Section 8.4.2 as the default eye width and height minimum ref‐
erences. Recommended values were taken from the PCIe Architecture PHY Test Spec Rev 5.0 (Transmitter Electrical Com‐
pliance).
Reference grading values currently used by the utility are presented in the table below:
┌─────┬─────────────────────┬──────────────────────┐
│ │ 16 GT/s (Gen 4) │ 32 GT/s (Gen 5) │
│ │ EW │ EH │ EW │ EH │
├─────┼──────────┼──────────┼───────────┼──────────┤
│ Min │ 18.75 ps │ 15 mV │ 9.375 ps │ 15 mV │
│ │ 30% UI │ │ 30% UI │ │
├─────┼──────────┼──────────┼───────────┼──────────┤
│ Rec │ 23.75 ps │ 21 mV │10.157 ps │19.75 mV │
│ │ 38% UI │ │33% UI │ │
└─────┴──────────┴──────────┴───────────┴──────────┘
pcilmr uses full eye width and height values to grade lanes. However, it is possible that device supports only one
side margining. In such cases by default utility will calculate EW or EH as a double one side result.
If info for specific device is available, you can configure grading criteria and tweak utility behavior in one-side
only cases for your device using -g link specific option (see below).
HARDWARE QUIRKS SUPPORT
Thanks to testing or directly from the manufacturer's documentation, we know that some devices require special treat‐
ment during the margining. Utility detects such devices based on their Vendor ID - Device ID pair. Right now the
list of special devices is hardcoded in margin_hw file. For such devices utility can automatically adjust port mar‐
gining parameters or grading options.
For example, for Ice Lake CPUs RC ports pcilmr will change device MaxVoltageOffset value and will force the use of
'one side is the whole' grading mode.
OPTIONS
Device Specifier
You can specify Downstream or Upstream Port of the Link.
[:]:. (see lspci(8))
Utility Modes
--margin ...
Margin selected Links.
--full Margin all ready for testing (in a meaning similar to the --scan option) Links in the system (one by one).
--scan Scan for Links with negotiated speed 16 GT/s or higher. Mark "Ready" those of them in which at least one of
the Link sides have Margining Ready bit set meaning that these Links are ready for testing and you can run
utility on them.
Margining Common (for all specified links) options
-c Print Device Lane Margining Capabilities only. Do not run margining.
-e
Specify Error Count Limit for margining.
Default: 4.
-o
Save margining results in csv form into the specified directory. Utility will generate file with the name in
form of "lmr__Rx#_.csv" for each successfully tested receiver.
-d