Package: pciutils
Version: 1:3.13.0-1+b1
Severity: minor
Tags: patch
N.B. What does the unit 'T' (in GT/s) stand for? (T is a symbol for the
unit 'tesla'.)
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':560: macro 'I'
troff: backtrace: file '<stdin>':40
troff:<stdin>:40: warning: trailing space in the line
troff: backtrace: file '<stdin>':102
troff:<stdin>:102: warning: trailing space in the line
troff: backtrace: file '<stdin>':142
troff:<stdin>:142: warning: tab character in unquoted macro argument
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls,
an-RS-open=1 at end of file
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':560: macro 'I'
troff: backtrace: file '<stdin>':40
troff:<stdin>:40: warning: trailing space in the line
troff: backtrace: file '<stdin>':142
troff:<stdin>:142: warning: tab character in unquoted macro argument
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls,
an-RS-open=1 at end of file
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.11.5-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages pciutils depends on:
ii libc6 2.40-3
ii libkmod2 33+20240816-2
ii libpci3 1:3.13.0-1+b1
pciutils recommends no packages.
Versions of packages pciutils suggests:
ii bzip2 1.0.8-6
ii curl 8.11.0-1
ii lynx 2.9.2-1
ii wget 1.24.5-2+b1
-- no debconf information
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output of 'diff -u' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint pcilmr.8": (shortened list)
23 input text line longer than 80 bytes
-.-.
Output from "test-groff -mandoc -t -ww -b -z pcilmr.8": (shortened list)
1 tab character in unquoted macro argument
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
pcilmr.8:6:.RB [ "--margin" ]
pcilmr.8:9:.B pcilmr --full
pcilmr.8:12:.B pcilmr --scan
pcilmr.8:148:.BI --margin " <downstream component> ..."
pcilmr.8:151:.B --full
pcilmr.8:153:.B --scan
pcilmr.8:156:.B --scan
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
9:.B pcilmr --full
12:.B pcilmr --scan
148:.BI --margin " <downstream component> ..."
151:.B --full
153:.B --scan
156:.B --scan
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
6:.RB [ "--margin" ]
9:.B pcilmr --full
12:.B pcilmr --scan
120:.I -g
127:Utility detects such devices based on their Vendor ID - Device ID pair.
148:.BI --margin " <downstream component> ..."
151:.B --full
153:.B --scan
156:.B --scan
161:.B -c
164:.BI -e " <errors>"
169:.BI -o " <directory>"
175:.BI -d " <time>"
190:\fB-r\fI <recvn>\fP[\fI,<recvn>...\fP]
195:.BI -p " <parallel_lanes>"
202:.I -p
207:.B "Use only one of -T/-t options at the same time (same for -V/-v)."
212:.B -T
216:.BI -t " <steps>"
219:.B -V
221:.I -T
224:.BI -v " <steps>"
227:\fB-g\fI <recvn>\fPt=\fI<criteria>\fP{%|ps}[,f]
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
245:.I -g
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"
-.-.
Test nr. 27:
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
256 .UR https://gist.github.com/bombanya/f2b15263712757ffba1a11eea011c419
-.-.
Test nr. 29:
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B.
The number of lines affected can be too large to be in a patch.
55:higher, including Pseudo Ports (Retimers). Lane Margining at Receiver
enables system
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,
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
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
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
130:file. For such devices utility can automatically adjust port margining
parameters
157:Scan for Links with negotiated speed 16 GT/s or higher. Mark "Ready" those
of them
162:Print Device Lane Margining Capabilities only. Do not run margining.
170:Save margining results in csv form into the specified directory. Utility
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
214:than an Error Count Limit. Use this option to find Link limit.
235:(voltage - v) for one of the link receivers. For EW you must choose one of
the
241:margining. In such cases by default utility will calculate EW or EH as a
242:double one side result. You can add
247:measurement of the full eye and it does not need to be multiplied. This is
so called
-.-.
Test nr. 30:
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
N.B.
The number of lines affected can be too large to be in a patch.
Line 7, length 112
.RI [ "<common options>" ] " <link port> " [ "<link options>" "] [" "<link
port> " [ "<link options>" ] " ..." ]
Line 31, length 89
.I "Configured by the user before running the utility, the utility does not
change them:"
Line 40, length 84
.I "Configured by the utility during operation, utility set them to their
original "
Line 46, length 96
The Hardware Autonomous Speed Disable bit of the Link Control 2 register must
be Set in both the
Line 49, length 94
The Hardware Autonomous Width Disable bit of the Link Control register must be
Set in both the
Line 54, length 82
capability which is mandatory for all Ports supporting a data rate of 16.0 GT/s
or
Line 55, length 84
higher, including Pseudo Ports (Retimers). Lane Margining at Receiver enables
system
Line 56, length 86
software to obtain the margin information of a given Receiver while the Link is
in the
Line 57, length 89
L0 state. The margin information includes both voltage and time, in either
direction from
Line 58, length 86
the current Receiver position. Margining support for timing is required, while
support
Line 59, length 91
for voltage is optional at 16.0 GT/s and required at 32.0 GT/s and higher data
rates. Also,
Line 62, length 89
Utility allows to get an approximation of the eye margin diagram in the form of
a rhombus
Line 63, length 88
(by four points). Lane Margining at the Receiver capability enables users to
margin PCIe
Line 64, length 89
links without a hardware debugger and without the need to stop the target
system. Utility
Line 68, length 89
requires root privileges (to access Extended Configuration Space), but during
our testing
Line 69, length 94
there were no problems with the devices and they successfully returned to their
normal initial
Line 73, length 96
The PCIe specification provides reference values for the eye diagram, which are
also used by the
Line 78, length 104
The utility uses values set in PCIe Base Spec Rev. 5.0 Section 8.4.2 as the
default eye width and height
Line 82, length 88
Reference grading values currently used by the utility are presented in the
table below:
Line 114, length 82
uses full eye width and height values to grade lanes. However, it is possible
that
Line 125, length 81
Thanks to testing or directly from the manufacturer's documentation, we know
that
Line 130, length 81
file. For such devices utility can automatically adjust port margining
parameters
Line 157, length 82
Scan for Links with negotiated speed 16 GT/s or higher. Mark "Ready" those of
them
Line 158, length 81
in which at least one of the Link sides have Margining Ready bit set meaning
that
Line 185, length 82
uses logical lane numbers in arguments and for logging. Utility will
automatically
Line 247, length 84
measurement of the full eye and it does not need to be multiplied. This is so
called
Line 253, length 104
.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"
-.-.
Use \(en (en-dash) for a dash between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
pcilmr.8:25:Intel VMD for NVMe SSDs - in case of strange behavior of the
pcilmr.8:127:Utility detects such devices based on their Vendor ID - Device ID
pair.
-.-.
Split a punctuation mark from a single argument for a two-font macro
26:.BR pcilmr,
-.-.
"[" and "]", showing optional arguments to options, should be typeset in roman.
229:.IB " <recvn>" t=f[, "<criteria>" "{%|ps}]"
231:.IB " <recvn>" v= "<criteria>" "[,f]"
233:.IB " <recvn>" v=f[, "<criteria>" ]
-.-.
No space is needed before a quote (") at the end of a line
40:.I "Configured by the utility during operation, utility set them to their
original "
-.-.
Space after an end of sentence.
55:higher, including Pseudo Ports (Retimers). Lane Margining at Receiver
enables system
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,
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
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
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
130:file. For such devices utility can automatically adjust port margining
parameters
143:.RI [ "<domain>" :] <bus> : <dev> . <func>
157:Scan for Links with negotiated speed 16 GT/s or higher. Mark "Ready" those
of them
162:Print Device Lane Margining Capabilities only. Do not run margining.
170:Save margining results in csv form into the specified directory. Utility
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
214:than an Error Count Limit. Use this option to find Link limit.
235:(voltage - v) for one of the link receivers. For EW you must choose one of
the
241:margining. In such cases by default utility will calculate EW or EH as a
242:double one side result. You can add
247:measurement of the full eye and it does not need to be multiplied. This is
so called
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':560: macro 'I'
troff: backtrace: file '<stdin>':40
troff:<stdin>:40: warning: trailing space in the line
troff: backtrace: file '<stdin>':142
troff:<stdin>:142: warning: tab character in unquoted macro argument
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls,
an-RS-open=1 at end of file
-.-.
Additionally (general):
FSF office address update. See
https://lists.gnu.org/archive/html/bug-gnulib/2024-09/msg00004.html
-.-
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
Table headers, that are wider than any data in the corresponding column,
do not need to be centered, so left adjustment is sufficient.
The default value for kerning (.kern) and ligature (.lg) is one (1),
so for n-mode (nroff) it should be set to zero (0) to avoid the processing
of unnecessary code.
--- pcilmr.8 2024-11-15 01:54:50.134236869 +0000
+++ pcilmr.8.new 2024-11-15 12:18:37.471660290 +0000
@@ -3,13 +3,13 @@
pcilmr \- margin PCIe Links
.SH SYNOPSIS
.B pcilmr
-.RB [ "--margin" ]
+.RB [ "\-\-margin" ]
.RI [ "<common options>" ] " <link port> " [ "<link options>" "] [" "<link
port> " [ "<link options>" ] " ..." ]
.br
-.B pcilmr --full
+.B pcilmr \-\-full
.RI [ "<common options>" ]
.br
-.B pcilmr --scan
+.B pcilmr \-\-scan
.SH CONFIGURATION
List of the requirements for links and system settings
to run the margining test.
@@ -22,8 +22,8 @@ Turn off PCIe Leaky Bucket Feature, Re-E
.IP \[bu]
Set Error Thresholds to 0;
.IP \[bu]
-Intel VMD for NVMe SSDs - in case of strange behavior of the
-.BR pcilmr,
+Intel VMD for NVMe SSDs \(en in case of strange behavior of the
+.BR pcilmr ,
try to run it with the VMD turned off.
.PP
.B Device (link) requirements:
@@ -37,7 +37,7 @@ utility supports 16 GT/s and 32 GT/s Lin
Link Downstream Component must be at D0 Power Management State.
.RE
.IP
-.I "Configured by the utility during operation, utility set them to their
original "
+.I "Configured by the utility during operation, utility set them to their
original"
.I "state after receiving the results:"
.RS
.IP \[bu] 3
@@ -48,6 +48,7 @@ Downstream Port and Upstream Port;
.IP \[bu]
The Hardware Autonomous Width Disable bit of the Link Control register must be
Set in both the
Downstream Port and Upstream Port.
+.RE
.SH DESCRIPTION
.B pcilmr
utility allows you to take advantage of the PCIe Lane Margining at the Receiver
@@ -117,14 +118,14 @@ calculate EW or EH as a double one side
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
-.I -g
+.I \-g
link specific option (see below).
.SH HARDWARE QUIRKS SUPPORT
Thanks to testing or directly from the manufacturer's documentation, we know
that
some devices require special treatment during the margining.
-Utility detects such devices based on their Vendor ID - Device ID pair.
+Utility detects such devices based on their Vendor ID \(en Device ID pair.
Right now the list of special devices is hardcoded in
.I margin_hw
file. For such devices utility can automatically adjust port margining
parameters
@@ -139,40 +140,40 @@ will change device MaxVoltageOffset valu
.SS Device Specifier
.B "You can specify Downstream or Upstream Port of the Link."
.TP
-.B "<device/component>" \t
+.B "<device/component> \t"
.RI [ "<domain>" :] <bus> : <dev> . <func>
(see
.BR lspci (8))
.SS Utility Modes
.TP
-.BI --margin " <downstream component> ..."
+.BI \-\-margin " <downstream component> ..."
Margin selected Links.
.TP
-.B --full
+.B \-\-full
Margin all ready for testing (in a meaning similar to the
-.B --scan
+.B \-\-scan
option) Links in the system (one by one).
.TP
-.B --scan
+.B \-\-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.
.SS Margining Common (for all specified links) options
-.B -c
+.B \-c
Print Device Lane Margining Capabilities only. Do not run margining.
.TP
-.BI -e " <errors>"
+.BI \-e " <errors>"
Specify Error Count Limit for margining.
.br
Default: 4.
.TP
-.BI -o " <directory>"
+.BI \-o " <directory>"
Save margining results in csv form into the specified directory. Utility
will generate file with the name in form of
.RI "\[dq]lmr_" "<port>" "_Rx" # _ <timestamp> ".csv\[dq]"
for each successfully tested receiver.
.TP
-.BI -d " <time>"
+.BI \-d " <time>"
Specify dwell time in seconds for the margining step.
.br
Default: 1 s
@@ -187,52 +188,52 @@ determine Lane Reversal and tune its cal
.br
Default: all link lanes.
.TP
-\fB-r\fI <recvn>\fP[\fI,<recvn>...\fP]
+\fB\-r\fI <recvn>\fP[\fI,<recvn>...\fP]
Specify Receivers to select margining targets.
.br
Default: all available Receivers (including Retimers).
.TP
-.BI -p " <parallel_lanes>"
+.BI \-p " <parallel_lanes>"
Specify number of lanes to margin simultaneously.
.br
According to spec it's possible for Receiver to margin up to MaxLanes + 1
lanes simultaneously, but during testing, performing margining on several
lanes simultaneously led to results that were different from sequential
margining, so this feature requires additional verification and
-.I -p
+.I \-p
option right now is for experiments mostly.
.br
Default: 1.
.PP
-.B "Use only one of -T/-t options at the same time (same for -V/-v)."
+.B "Use only one of \-T/\-t options at the same time (same for \-V/\-v)."
.br
.B "Without these options utility will use MaxSteps from Device"
.B "capabilities as test limit."
.TP
-.B -T
+.B \-T
Time Margining will continue until the Error Count is no more
than an Error Count Limit. Use this option to find Link limit.
.TP
-.BI -t " <steps>"
+.BI \-t " <steps>"
Specify maximum number of steps for Time Margining.
.TP
-.B -V
+.B \-V
Same as
-.I -T
+.I \-T
option, but for Voltage.
.TP
-.BI -v " <steps>"
+.BI \-v " <steps>"
Specify maximum number of steps for Voltage Margining.
.TP
-\fB-g\fI <recvn>\fPt=\fI<criteria>\fP{%|ps}[,f]
+\fB\-g\fI <recvn>\fPt=\fI<criteria>\fP{%|ps}\fR[\fP,f\fR]\fP
.TP
-.IB " <recvn>" t=f[, "<criteria>" "{%|ps}]"
+.IB " <recvn>" t=f\fR[\fP, "<criteria>" "{%\fR|\fPps}\fR]\fP"
.TP
-.IB " <recvn>" v= "<criteria>" "[,f]"
+.IB " <recvn>" v= "<criteria>" "\fR[\fP,f\fR]\fP"
.TP
-.IB " <recvn>" v=f[, "<criteria>" ]
-Specify pass/fail grading criteria for eye width (timing - t) or height
-(voltage - v) for one of the link receivers. For EW you must choose one of the
+.IB " <recvn>" v=f\fR[\fP, "<criteria>" \fR]\fP
+Specify pass/fail grading criteria for eye width (timing \-t) or height
+(voltage \-v) for one of the link receivers. For EW you must choose one of the
units (% UI or ps), for EH mV is used.
.br
Additional flag
@@ -242,7 +243,7 @@ margining. In such cases by default util
double one side result. You can add
.I f
flag for
-.I -g
+.I \-g
option to tell the utility that the result in one direction is actually the
measurement of the full eye and it does not need to be multiplied. This is so
called
.RI ' "one side is the whole" "' grading mode."
@@ -250,10 +251,10 @@ measurement of the full eye and it does
.SH EXAMPLES
Utility syntax example:
.RS
-.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"
+.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"
.RE
-.UR https://gist.github.com/bombanya/f2b15263712757ffba1a11eea011c419
+.UR https://gist.github.com/\:bombanya/\:f2b15263712757ffba1a11eea011c419
Examples of collected results on different systems.
.UE
