Re: git: bf8f6ffcb66a - main - Mention kern.timecounter.alloweddeviation in nanosleep.1

On Sat, Oct 09, 2021 at 06:18:48AM +0000, Piotr P. Stefaniak wrote:
> On 2021-10-09 08:53:08, Konstantin Belousov wrote:
> > On Fri, Oct 08, 2021 at 03:09:04PM +0000, Piotr Pawel Stefaniak wrote:
> > > @@ -93,6 +93,8 @@ returns immediately and the calling thread is not suspended.
> > >  .Pp
> > >  The suspension time may be longer than requested due to the
> > >  scheduling of other activity by the system.
> > > +It is also subject to the allowed time interval deviation
> > > +specified by the sysctl kern.timecounter.alloweddeviation.
> > This should be like
> > .Xr sysctl 3
> > .Dv kern.timecounter.alloweddeviation
> 
> @@ -94,7 +94,9 @@ returns immediately and the calling thread is not suspended.
>  The suspension time may be longer than requested due to the
>  scheduling of other activity by the system.
>  It is also subject to the allowed time interval deviation
> -specified by the sysctl kern.timecounter.alloweddeviation.
> +specified by the
> +.Xr sysctl 3
> +.Dv kern.timecounter.alloweddeviation .
>  An unmasked signal will terminate the sleep early, regardless of the
>  .Dv SA_RESTART
>  value on the interrupting signal.
> 
> > And then, it is missing a description what exactly is allowed by deviation,
> > for instance, what units this sysctl is?
> 
> That would be redundant with sysctl -d. The point of this change is that now
> the user is much more likely to know of the sysctl and can look it up and read
> all about it.
> 
sysctl -d is not a (good) documentation.  When you read a man text, you are
supposed to get everything that is relevant there, although it might be
terse and requiring making logical deduction.  This is not the case there.

Anyway, I went ahead and did what you suggested.  On one of my machines,
I got
solo% sysctl -d kern.timecounter.alloweddeviation
kern.timecounter.alloweddeviation: 
solo%

On another,
v1%  sysctl -d kern.timecounter.alloweddeviation                              ~
kern.timecounter.alloweddeviation: Allowed time interval deviation in percents

Slightly more useful, but still.  Percents of what?

Imagine somebody reads the man page in the browser from Linux.  Where should
he search for the sysctl description?

> The bug may be that there isn't much documentation to be read about it, only
> sysctl -d and kern_tc.c.
> 
> The only thing I worry that may be missing from this change is this reference
> in any other manual pages that might need it as much as nanosleep.
Well, nanosleep is just an example of a syscall requesting timeout.
Another poster childs there are select(2), and poll(2) family which
explicitly use precision.

To get the definitive list, you would need to review all uses of
callout_reset() variants.