[PATCH] adjtimex.2: Add details about ADJ_FREQUENCY

[PATCH] adjtimex.2: Add details about ADJ_FREQUENCY

[Laurent Georget]

[-- Attachment #1: Type: text/plain, Size: 1329 bytes --]

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

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 18823c8..2652fc6 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

Re: [PATCH] adjtimex.2: Add details about ADJ_FREQUENCY

[Richard Cochran]

On Tue, Dec 30, 2014 at 06:19:41PM +0100, Laurent Georget wrote:
> 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
> 
> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
> index 18823c8..2652fc6 100644
> --- a/man2/adjtimex.2
> +++ b/man2/adjtimex.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 */

> +                         (parts per million) :
> +                         the scaling unit of timex.freq is 2^16 usec =
> 1000*2^16 nsec.

Your mailer is wrapping lines here ...

>      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.

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.

> +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
> 

Re: [PATCH] adjtimex.2: Add details about ADJ_FREQUENCY

[Laurent Georget]

[-- Attachment #1: Type: text/plain, Size: 2073 bytes --]

Hi again,

Le 30/12/2014 19:05, Richard Cochran a écrit :
>> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
>> index 18823c8..2652fc6 100644
>> --- a/man2/adjtimex.2
>> +++ b/man2/adjtimex.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 */
>

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.

>> +                         (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.

> 
>>      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.
> 
> 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.
> 

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

[PATCH] adjtimex: PPM scaling is by 2^-16

[Jeff Epler]

Signed-off-by: Jeff Epler <jepler@unpythonic.net>
---
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(-)

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 4b558b7..118908a 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -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) */
-- 
2.1.4

Re: [PATCH] adjtimex: PPM scaling is by 2^-16

[Richard Cochran]

On Thu, Jan 01, 2015 at 08:41:20PM -0600, Jeff Epler wrote:
> 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.

> -    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

[Laurent Georget]

[-- Attachment #1: Type: text/plain, Size: 3396 bytes --]

Hi,

Le 02/01/2015 07:29, Richard Cochran a écrit :
> On Thu, Jan 01, 2015 at 08:41:20PM -0600, Jeff Epler wrote:
>> 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.
> 
>> -    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.
> 

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(-)

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 18823c8..ff4b23e 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -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
-- 
2.0.4

Laurent


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

Re: [PATCH] adjtimex: PPM scaling is by 2^-16

[Richard Cochran]

On Fri, Jan 02, 2015 at 05:39:17PM +0100, Laurent Georget wrote:
> 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

Re: [PATCH] adjtimex: PPM scaling is by 2^-16

[Jeff Epler]

On Fri, Jan 02, 2015 at 05:39:17PM +0100, Laurent Georget wrote:
> +    long freq;        /* Frequency offset, in units of 2^-16 PPM
> +                         (parts per million) (see NOTES below) */
...
> +.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.

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

Reviewed-by: Jeff Epler <jepler@unpythonic.net>

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

Re: [PATCH] adjtimex: PPM scaling is by 2^-16

[Laurent Georget]

[-- Attachment #1: Type: text/plain, Size: 557 bytes --]

Le 02/01/2015 22:15, Jeff Epler a écrit :
> However, the patch got line-wrapped again (I fixed it manually above).
> With line-wrapped fix, consider it
> 
> Reviewed-by: Jeff Epler <jepler@unpythonic.net>

Sorry, I'm giving up on 'normal' email clients to send patchs. 'git
format-patch' and 'mutt' will do.

> 
> 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



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

[PATCH 1/2] adjtimex.2: Clarify the 'ppm scaling' used in struct timex

[Laurent Georget]

[-- Attachment #1: Type: text/plain, Size: 2794 bytes --]

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.

Reviewed-By: Jeff Epler <jepler@unpythonic.net>

---
 man2/adjtimex.2 | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 18823c8..ff4b23e 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -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
-- 
2.0.4



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'

[Laurent Georget]

[-- Attachment #1: Type: text/plain, Size: 3075 bytes --]

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@unpythonic.net>.

---
 man2/adjtimex.2 | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index ff4b23e..dbb2333 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -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
-- 
2.0.4



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 213 bytes --]

Re: [PATCH 2/2] adjtimex.2: Change 'PPM' (parts per million) to 'ppm'

[Michael Kerrisk (man-pages)]

On 01/03/2015 12:07 AM, Laurent Georget wrote:
> 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@unpythonic.net>.

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

> 
> ---
>  man2/adjtimex.2 | 15 +++++++--------
>  1 file changed, 7 insertions(+), 8 deletions(-)
> 
> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
> index ff4b23e..dbb2333 100644
> --- a/man2/adjtimex.2
> +++ b/man2/adjtimex.2
> @@ -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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 1/2] adjtimex.2: Clarify the 'ppm scaling' used in struct timex

[Michael Kerrisk (man-pages)]

Hi Laurent,

On 01/03/2015 12:01 AM, Laurent Georget wrote:
> 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.

> Reviewed-By: Jeff Epler <jepler@unpythonic.net>

And for good measure I threw in a "Reviewed-by" from Richard as well.

Thanks,

Michael


> 
> ---
>  man2/adjtimex.2 | 21 ++++++++++++++++-----
>  1 file changed, 16 insertions(+), 5 deletions(-)
> 
> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
> index 18823c8..ff4b23e 100644
> --- a/man2/adjtimex.2
> +++ b/man2/adjtimex.2
> @@ -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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/