adjtimex.2: Add details about ADJ_FREQUENCY
PATCH 1/1 adjtimex.2: Add details about ADJ_FREQUENCY
Hi,
this is another patch for adjtimex(2) man page which fixes a FIXME by giving the scaling unit of timex.freq and adds a detail about the value expected by ADJ_FREQUENCY.
Laurent
man2/adjtimex.2 +2 -2
@@ -55,8 +55,8 @@ struct timex { status flag is set, otherwise microseconds */ long freq; /* Frequency offset, as scaled PPM - (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ? + (parts per million) : + the scaling unit of timex.freq is 2^16 usec =
1000*2^16 nsec.
long maxerror; /* Maximum error (microseconds) */
long esterror; /* Estimated error (microseconds) */
int status; /* Clock command/status */@@ -106,6 +106,10 @@ Set time offset from
.BR ADJ_FREQUENCY
Set frequency offset from
.IR buf.freq .
+The clock frequency must be comprised between -500000 and 500000 scaled ns/s.
+If the given value is outside those bounds, it is silently truncated. This +corresponds to values between -32768000 and 32768000 for
+.IR buf.freq .
.TP
.BR ADJ_MAXERROR
Set maximum time error from
Quoted 13 lines · Laurent Georget
Hi,
this is another patch for adjtimex(2) man page which fixes a FIXME by giving the scaling unit of timex.freq and adds a detail about the value expected by
ADJ_FREQUENCY.Laurent
man2/adjtimex.2 +0
-0
man2/adjtimex.2 struct timex { · line 59
Quoted 5 lines
man2/adjtimex.2 +0
-2@@ -55,8 +55,8 @@ struct timex { status flag is set, otherwise microseconds */ long freq; /* Frequency offset, as scaled PPM - (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ?
Your text sounds funny and seems unclear to me. How about something more like this:
long freq /* Frequency offset in PPM with a 16 bit
factional field */
Quoted 3 lines
man2/adjtimex.2 +2
-0+ (parts per million) : + the scaling unit of timex.freq is 2^16 usec =1000*2^16 nsec.
Your mailer is wrapping lines here ...
Quoted 9 lines
long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */ int status; /* Clock command/status */man2/adjtimex.2 +1
-0@@ -106,6 +106,10 @@ Set time offset from .BR ADJ_FREQUENCY Set frequency offset from .IR buf.freq . +The clock frequency must be comprised between -500000 and 500000 scaledns/s.
and here.
The phrase "must be comprised" does not make any sense in this context. How about this instead?
The allowed frequency range is -500 PPM to +500 PPM.
man2/adjtimex.2
Quoted 7 lines
man2/adjtimex.2 +3
-0+If the given value is outside those bounds, it is silently truncated. This +corresponds to values between -32768000 and 32768000 for +.IR buf.freq . .TP .BR ADJ_MAXERROR Set maximum time error from
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi again,
Quoted 14 lines · Richard Cochran
man2/adjtimex.2 struct timex { · line 59
Quoted 10 lines
man2/adjtimex.2 +0
-2@@ -55,8 +55,8 @@ struct timex { status flag is set, otherwise microseconds */ long freq; /* Frequency offset, as scaled PPM - (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ?Your text sounds funny and seems unclear to me. How about something more like this:
Quoted 3 lines
long freq /* Frequency offset in PPM with a 16 bit
factional field */
I tried to phrase it as in the FIXME, but of course, that may not be the best thing to do. I'm not sure to understand what you mean however in your corrected comment for freq.
Quoted 6 lines
Quoted 3 lines
man2/adjtimex.2 +2
-0+ (parts per million) : + the scaling unit of timex.freq is 2^16 usec =1000*2^16 nsec.
Your mailer is wrapping lines here ...
Indeed, it wrapped at 80 characters. I fixed it. Sorry about that.
Quoted 13 lines
Quoted 10 lines
long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */ int status; /* Clock command/status */man2/adjtimex.2 +1
-0@@ -106,6 +106,10 @@ Set time offset from .BR ADJ_FREQUENCY Set frequency offset from .IR buf.freq . +The clock frequency must be comprised between -500000 and 500000 scaledns/s.
and here.
Quoted 5 lines
The phrase "must be comprised" does not make any sense in this context. How about this instead?
The allowed frequency range is -500 PPM to +500 PPM.
Sorry for my poor english.
I have a doubt about the calculations here.
If I understand the code correctly (and I'd like to, as I'm using it) the input value is scaled with SHIFT_USEC whereas MAXFREQ is not. So, PPM is not exactly the same unit here and above (in struct timex). How should we phrase that?
Thanks
Laurent
PATCH 1/1 adjtimex: PPM scaling is by 2^-16
In reply to Laurent Georget---
Like Laurent Georget, I found by reading ntpd source the scale is 2^16 (i.e., 1 ~= 1.5e-5 ppm, 65536 = 1ppm)
Perhaps a wording like the following is suitable.
man2/adjtimex.2 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)
man2/adjtimex.2 +3 -4
@@ -54,9 +54,8 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, as scaled PPM + long freq; /* Frequency offset, in units of 2^-16 PPM (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ? long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */ int status; /* Clock command/status */
@@ -72,13 +71,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (scaled PPM, read-only) */ + (2^-16 PPM, read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (scaled PPM, read-only) */ + long stabil; /* PPS stability (2^-16 PPM, read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */
Signature · 5 lines
2.1.4 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] adjtimex: PPM scaling is by 2^-16
Quoted 2 lines · Jeff Epler
Like Laurent Georget, I found by reading ntpd source the scale is 2^16 (i.e., 1 ~= 1.5e-5 ppm, 65536 = 1ppm)
Yep, you wont find this documented in prose anywhere, not even at ntp.org.
man2/adjtimex.2 struct timex { · line 58
Quoted 3 lines
man2/adjtimex.2 +1
-1- long freq; /* Frequency offset, as scaled PPM + long freq; /* Frequency offset, in units of 2^-16 PPM (parts per million) */
This wording is correct.
IMHO, it is more understandable when you explain that this field is a fixed point number, with a 16 bit binary fraction. For example, see the comment in the function, ppb_to_scaled_ppm(), in Documentation/ptp/testptp.c.
Thanks,
Richard
Re: [PATCH] adjtimex: PPM scaling is by 2^-16
Hi,
Quoted 11 lines · Richard Cochran
Quoted 2 lines · Jeff Epler
Like Laurent Georget, I found by reading ntpd source the scale is 2^16 (i.e., 1 ~= 1.5e-5 ppm, 65536 = 1ppm)
Yep, you wont find this documented in prose anywhere, not even at ntp.org.
Review
Quoted 3 lines
(quoted diff) +1
-1- long freq; /* Frequency offset, as scaled PPM + long freq; /* Frequency offset, in units of 2^-16 PPM (parts per million) */
Quoted 7 lines
This wording is correct.
IMHO, it is more understandable when you explain that this field is a fixed point number, with a 16 bit binary fraction. For example, see the comment in the function,
ppb_to_scaled_ppm(), inDocumentation/ptp/testptp.c.
Ah, ok, I finally understood what you meant by "fractional part". Perhaps we could explicit it in the man page like in the following patch?
--- man2/adjtimex.2 | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-)
man2/adjtimex.2 +4 -5
@@ -54,9 +54,8 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, as scaled PPM - (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ? + long freq; /* Frequency offset, in units of 2^-16 PPM + (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */ int status; /* Clock command/status */
@@ -72,13 +71,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (scaled PPM, read-only) */ + (2^-16 PPM (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (scaled PPM, read-only) */ + long stabil; /* PPS stability (2^-16 PPM (see NOTES),
read-only) */
long jitcnt; /* PPS jitter limit exceeded (read-only) */
long calcnt; /* PPS calibration intervals (read-only) */
long errcnt; /* PPS calibration errors (read-only) */@@ -343,6 +342,18 @@ and the caller does not have sufficient privilege.
Under Linux, the
.B CAP_SYS_TIME
capability is required.
+.SH NOTES
+In struct
+.IR timex ,
+.IR freq ,
+.IR ppsfreq ,
+and
+.I stabil
+are PPM (parts per million) with a 16-bits fractional part, which means that a
+value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is
+1 PPM. This is the case for both input values (in the case of +.IR freq )
+and output values.
.SH CONFORMING TO
.BR adjtimex ()
is Linux-specific and should not be used in programs
Signature · 3 lines
2.0.4 Laurent
Re: [PATCH] adjtimex: PPM scaling is by 2^-16
Quoted 2 lines · Laurent Georget
Ah, ok, I finally understood what you meant by "fractional part". Perhaps we could explicit it in the man page like in the following patch?
Much improved. Looks good to me.
Thanks,
Richard
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Jeff Epler
Reviewed-byRe: [PATCH] adjtimex: PPM scaling is by 2^-16
In reply to Laurent GeorgetQuoted 2 lines · Laurent Georget
man2/adjtimex.2 +2
-0+ long freq; /* Frequency offset, in units of 2^-16 PPM + (parts per million) (see NOTES below) */
...
Review
Quoted 12 lines
+.SH NOTES
(quoted diff) +11
-0+In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and +.I stabil +are PPM (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is +1 PPM. This is the case for both input values (in the case of +.IR freq ) +and output values.
I appreciate the addition of the NOTES section, this is likely to be unclear to first-time readers and that section should clear it up nicely. Giving the definition of PPM as "parts per million" is good too.
However, the patch got line-wrapped again (I fixed it manually above). With line-wrapped fix, consider it
hm, as a separate issue, "ppm" seems to typically be written in lowercase. see e.g., http://en.wikipedia.org/wiki/Parts-per_notation
Jeff
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] adjtimex: PPM scaling is by 2^-16
Quoted 4 lines · Jeff Epler
However, the patch got line-wrapped again (I fixed it manually above). With line-wrapped fix, consider it
Sorry, I'm giving up on 'normal' email clients to send patchs. 'git format-patch' and 'mutt' will do.
Quoted 4 lines
hm, as a separate issue, "ppm" seems to typically be written in lowercase. see e.g., http://en.wikipedia.org/wiki/Parts-per_notation
That's right. I'll send the coresponding fix in another patch.
Thanks
Laurent
PATCH 1/2 adjtimex.2: Clarify the 'ppm scaling' used in struct timex
In reply to Laurent GeorgetHi,
this is the last version of a new series of patchs for adjtimex.2. Please ignore all previous versions of this series.
This patch makes explicit and clarifies the unit used for fields "freq", "ppsfreq" and "stabil" in struct timex. It closes a FIXME in the man page.
--- man2/adjtimex.2 | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-)
man2/adjtimex.2 +16 -5
@@ -54,9 +54,8 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, as scaled PPM - (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ? + long freq; /* Frequency offset, in units of 2^-16 PPM + (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */ int status; /* Clock command/status */
@@ -72,13 +71,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (scaled PPM, read-only) */ + (2^-16 PPM (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (scaled PPM, read-only) */ + long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */
@@ -343,6 +342,18 @@ and the caller does not have sufficient privilege. Under Linux, the .B CAP_SYS_TIME capability is required. +.SH NOTES +In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and +.I stabil +are PPM (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is +1 PPM. This is the case for both input values (in the case of +.IR freq ) +and output values. .SH CONFORMING TO .BR adjtimex () is Linux-specific and should not be used in programs
Signature · 1 line
2.0.4
Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'
Hi again,
this is the second patch of the new series of patchs for adjtimex.2.
This is a trivia patch correcting "PPM" (parts per million) to the more usual "ppm". Credits to Jeff Epler <[email protected]>.
--- man2/adjtimex.2 | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-)
man2/adjtimex.2 +7 -8
@@ -54,7 +54,7 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, in units of 2^-16 PPM + long freq; /* Frequency offset, in units of 2^-16 ppm (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */
@@ -62,8 +62,7 @@ struct timex { long constant; /* PLL (phase-locked loop) time constant */ long precision; /* Clock precision (microseconds, read-only) */ - long tolerance; /* Clock frequency tolerance (PPM, - read-only) */ + long tolerance; /* Clock frequency tolerance (ppm, read-only) */ struct timeval time; /* Current time (read-only, except for ADJ_SETOFFSET); upon return, time.tv_usec
@@ -71,13 +70,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (2^-16 PPM (see NOTES), read-only) */ + (2^-16 ppm (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only) */ + long stabil; /* PPS stability (2^-16 ppm (see NOTES), read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */
@@ -349,9 +348,9 @@ In struct .IR ppsfreq , and .I stabil -are PPM (parts per million) with a 16-bits fractional part, which means that a -value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is -1 PPM. This is the case for both input values (in the case of +are ppm (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 ppm, and 2^16=65535 is +1 ppm. This is the case for both input values (in the case of .IR freq ) and output values. .SH CONFORMING TO
Signature · 1 line
2.0.4
Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'
Quoted 7 lines · Laurent Georget
Hi again,
this is the second patch of the new series of patchs for adjtimex.2.
This is a trivia patch correcting "PPM" (parts per million) to the more usual "ppm".
Credits to Jeff Epler <jepler-ixP+gI44yfQ4d9/[email protected]>.
Thanks, Laurent (andf Jeff). Patch applied.
Laurent, please watch out: your patches are injecting trailing white space on lines. My release scripts clean those up, but it means that patches apply with "noise".
Cheers,
Michael
Quoted 58 lines
--- man2/adjtimex.2 | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-)man2/adjtimex.2 +7
-8@@ -54,7 +54,7 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, in units of 2^-16 PPM + long freq; /* Frequency offset, in units of 2^-16 ppm (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */@@ -62,8 +62,7 @@ struct timex { long constant; /* PLL (phase-locked loop) time constant */ long precision; /* Clock precision (microseconds, read-only) */ - long tolerance; /* Clock frequency tolerance (PPM, - read-only) */ + long tolerance; /* Clock frequency tolerance (ppm, read-only) */ struct timeval time; /* Current time (read-only, except for ADJ_SETOFFSET); upon return, time.tv_usec@@ -71,13 +70,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (2^-16 PPM (see NOTES), read-only) */ + (2^-16 ppm (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only) */ + long stabil; /* PPS stability (2^-16 ppm (see NOTES), read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */@@ -349,9 +348,9 @@ In struct .IR ppsfreq , and .I stabil -are PPM (parts per million) with a 16-bits fractional part, which means that a -value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is -1 PPM. This is the case for both input values (in the case of +are ppm (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 ppm, and 2^16=65535 is +1 ppm. This is the case for both input values (in the case of .IR freq ) and output values. .SH CONFORMING TO
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'
Hi
Quoted 3 lines · Michael Kerrisk (man-pages)
Laurent, please watch out: your patches are injecting trailing white space on lines. My release scripts clean those up, but it means that patches apply with "noise".
Really? I see no extra whitespace in my diff. Where do they come? Anyway, I'll take extra care next time. Thank you.
Laurent
Quoted 60 lines
Quoted 58 lines
--- man2/adjtimex.2 | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-)man2/adjtimex.2 +7
-8@@ -54,7 +54,7 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, in units of 2^-16 PPM + long freq; /* Frequency offset, in units of 2^-16 ppm (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */@@ -62,8 +62,7 @@ struct timex { long constant; /* PLL (phase-locked loop) time constant */ long precision; /* Clock precision (microseconds, read-only) */ - long tolerance; /* Clock frequency tolerance (PPM, - read-only) */ + long tolerance; /* Clock frequency tolerance (ppm, read-only) */ struct timeval time; /* Current time (read-only, except for ADJ_SETOFFSET); upon return, time.tv_usec@@ -71,13 +70,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (2^-16 PPM (see NOTES), read-only) */ + (2^-16 ppm (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only) */ + long stabil; /* PPS stability (2^-16 ppm (see NOTES), read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */@@ -349,9 +348,9 @@ In struct .IR ppsfreq , and .I stabil -are PPM (parts per million) with a 16-bits fractional part, which means that a -value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is -1 PPM. This is the case for both input values (in the case of +are ppm (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 ppm, and 2^16=65535 is +1 ppm. This is the case for both input values (in the case of .IR freq ) and output values. .SH CONFORMING TO
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'
Quoted 10 lines · Laurent Georget
Hi
Quoted 3 lines · Michael Kerrisk (man-pages)
Laurent, please watch out: your patches are injecting trailing white space on lines. My release scripts clean those up, but it means that patches apply with "noise".
Really? I see no extra whitespace in my diff. Where do they come? Anyway, I'll take extra care next time. Thank you.
Hi Laurent,
Looking more closely, it seems like your workflow may still be mangling the patches. Here's a portion of what landed when I save your message to a text file:
[[
- long stabil; /* PPS stability (scaled PPM, read-only) */
+ long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only=
) */
long jitcnt; /* PPS jitter limit exceeded (read-only) */
long calcnt; /* PPS calibration intervals (read-only) */
long errcnt; /* PPS calibration errors (read-only) */@@ -343,6 +342,18 @@ and the caller does not have sufficient privilege.
Under Linux, the
.B CAP_SYS_TIME
capability is required.
+.SH NOTES
+In struct
+.IR timex ,
+.IR freq ,
+.IR ppsfreq ,
+and=20
+.I stabil
+are PPM (parts per million) with a 16-bits fractional part, which means = that a
+value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=3D6= 5535 is=20
+1 PPM. This is the case for both input values (in the case of +.IR freq )
+and output values.
.SH CONFORMING TO
.BR adjtimex ()
is Linux-specific and should not be used in programs
--=20
]]
Note, for example, the line with 'long stabil', and the lines from 'are PPM (parts per million)' onward. Surprisingly, this all seemed to apply okay, just with some noise.
Thanks,
Michael
Quoted 60 lines
Quoted 59 lines
Quoted 57 lines
--- man2/adjtimex.2 | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-)man2/adjtimex.2 +7
-8@@ -54,7 +54,7 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, in units of 2^-16 PPM + long freq; /* Frequency offset, in units of 2^-16 ppm (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */@@ -62,8 +62,7 @@ struct timex { long constant; /* PLL (phase-locked loop) time constant */ long precision; /* Clock precision (microseconds, read-only) */ - long tolerance; /* Clock frequency tolerance (PPM, - read-only) */ + long tolerance; /* Clock frequency tolerance (ppm, read-only) */ struct timeval time; /* Current time (read-only, except for ADJ_SETOFFSET); upon return, time.tv_usec@@ -71,13 +70,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (2^-16 PPM (see NOTES), read-only) */ + (2^-16 ppm (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only) */ + long stabil; /* PPS stability (2^-16 ppm (see NOTES), read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */@@ -349,9 +348,9 @@ In struct .IR ppsfreq , and .I stabil -are PPM (parts per million) with a 16-bits fractional part, which means that a -value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is -1 PPM. This is the case for both input values (in the case of +are ppm (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 ppm, and 2^16=65535 is +1 ppm. This is the case for both input values (in the case of .IR freq ) and output values. .SH CONFORMING TO
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'
Quoted 1 line · Michael Kerrisk (man-pages)
Hi Laurent,
Hi
Quoted 33 lines
Looking more closely, it seems like your workflow may still be mangling the patches. Here's a portion of what landed when I save your message to a text file:
[[
(quoted diff) +1
-1- long stabil; /* PPS stability (scaled PPM, read-only) */ + long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only=) */
long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */(quoted diff) +8
-0@@ -343,6 +342,18 @@ and the caller does not have sufficient privilege. Under Linux, the .B CAP_SYS_TIME capability is required. +.SH NOTES +In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and=20 +.I stabil +are PPM (parts per million) with a 16-bits fractional part, which means =that a
+value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=3D6= 5535 is=20
+1 PPM. This is the case for both input values (in the case of +.IR freq )
+and output values.
.SH CONFORMING TO
.BR adjtimex ()
is Linux-specific and should not be used in programs
--=20
]]
Quoted 4 lines
Note, for example, the line with 'long stabil', and the lines from 'are PPM (parts per million)' onward. Surprisingly, this all seemed to apply okay, just with some noise.
Indeed, that's very bad. I didn't notice that because I tested my patch before sending it. I copied and pasted the patch in a new file and it applied correctly, without strange characters. Maybe the mangling comes from the mailer when it adds the PGP signature. I'll try without.
Again, I'm sorry about all this. I hope it'll work better now and that I'll stop wasting your time instead of helping...
Laurent
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/2] adjtimex.2: Clarify the 'ppm scaling' used in struct timex
In reply to Laurent GeorgetHi Laurent,
Quoted 8 lines · Laurent Georget
Hi,
this is the last version of a new series of patchs for adjtimex.2. Please ignore all previous versions of this series.
This patch makes explicit and clarifies the unit used for fields "freq", "ppsfreq" and "stabil" in struct timex.
It closes a FIXME in the man page.
Thanks -- nice work pulling together the input of Richard and Jeff. Patch applied.
Quoted 1 line
And for good measure I threw in a "Reviewed-by" from Richard as well.
Thanks,
Michael
Quoted 57 lines
--- man2/adjtimex.2 | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-)man2/adjtimex.2 +16
-5@@ -54,9 +54,8 @@ struct timex { long offset; /* Time offset; nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ - long freq; /* Frequency offset, as scaled PPM - (parts per million) */ -.\" FIXME What is the scaling unit of timex.freq? 2^16 ? + long freq; /* Frequency offset, in units of 2^-16 PPM + (parts per million) (see NOTES below) */ long maxerror; /* Maximum error (microseconds) */ long esterror; /* Estimated error (microseconds) */ int status; /* Clock command/status */@@ -72,13 +71,13 @@ struct timex { flag is set, otherwise microseconds */ long tick; /* Microseconds between clock ticks */ long ppsfreq; /* PPS (pulse per second) frequency - (scaled PPM, read-only) */ + (2^-16 PPM (see NOTES), read-only) */ long jitter; /* PPS jitter (read-only); nanoseconds, if STA_NANO status flag is set, otherwise microseconds */ int shift; /* PPS interval duration (seconds, read-only) */ - long stabil; /* PPS stability (scaled PPM, read-only) */ + long stabil; /* PPS stability (2^-16 PPM (see NOTES), read-only) */ long jitcnt; /* PPS jitter limit exceeded (read-only) */ long calcnt; /* PPS calibration intervals (read-only) */ long errcnt; /* PPS calibration errors (read-only) */@@ -343,6 +342,18 @@ and the caller does not have sufficient privilege. Under Linux, the .B CAP_SYS_TIME capability is required. +.SH NOTES +In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and +.I stabil +are PPM (parts per million) with a 16-bits fractional part, which means that a +value of 1 in one of those fields actually means 2^-16 PPM, and 2^16=65535 is +1 PPM. This is the case for both input values (in the case of +.IR freq ) +and output values. .SH CONFORMING TO .BR adjtimex () is Linux-specific and should not be used in programs
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html