From 55525729a12626a4268858c5994ec97153753e98 Mon Sep 17 00:00:00 2001 From: brooks Date: Fri, 17 Sep 2004 07:24:18 +0000 Subject: [PATCH] Bring kernel time variable and access function docs up to date by updating the list of variables and mentioning the bin(up)time functions. --- share/man/man9/Makefile | 12 ++- share/man/man9/microtime.9 | 45 ++++++++--- share/man/man9/microuptime.9 | 39 +++++++--- share/man/man9/time.9 | 144 +++++++++++++++-------------------- 4 files changed, 130 insertions(+), 110 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index ee6a34ef9d6e..aa1e80d374fe 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -609,10 +609,14 @@ MLINKS+=mdchain.9 md_append_record.9 \ mdchain.9 md_get_uio.9 \ mdchain.9 md_initm.9 \ mdchain.9 md_next_record.9 -MLINKS+=microtime.9 getmicrotime.9 \ +MLINKS+=microtime.9 bintime.9 \ + microtime.9 getbintime.9 \ + microtime.9 getmicrotime.9 \ microtime.9 getnanotime.9 \ microtime.9 nanotime.9 -MLINKS+=microuptime.9 getmicrouptime.9 \ +MLINKS+=microuptime.9 binuptime.9 \ + microuptime.9 getbinuptime.9 \ + microuptime.9 getmicrouptime.9 \ microuptime.9 getnanouptime.9 \ microuptime.9 nanouptime.9 MLINKS+=mi_switch.9 cpu_switch.9 \ @@ -854,8 +858,8 @@ MLINKS+=taskqueue.9 TASK_INIT.9 \ taskqueue.9 taskqueue_free.9 \ taskqueue.9 taskqueue_run.9 MLINKS+=time.9 boottime.9 \ - time.9 mono_time.9 \ - time.9 runtime.9 + time.9 time_second.9 \ + time.9 time_uptime.9 MLINKS+=timeout.9 callout_drain.9 \ timeout.9 callout_handle_init.9 \ timeout.9 callout_init.9 \ diff --git a/share/man/man9/microtime.9 b/share/man/man9/microtime.9 index 7783c32eb76e..7926dba92bbd 100644 --- a/share/man/man9/microtime.9 +++ b/share/man/man9/microtime.9 @@ -24,10 +24,12 @@ .\" .\" $FreeBSD$ .\" -.Dd January 3, 2000 +.Dd September 16, 2004 .Dt MICROTIME 9 .Os .Sh NAME +.Nm bintime , +.Nm getbintime , .Nm microtime , .Nm getmicrotime , .Nm nanotime , @@ -36,6 +38,10 @@ .Sh SYNOPSIS .In sys/time.h .Ft void +.Fn bintime "struct bintime *bt" +.Ft void +.Fn getbintime "struct bintime *bt" +.Ft void .Fn microtime "struct timeval *tv" .Ft void .Fn getmicrotime "struct timeval *tv" @@ -45,40 +51,51 @@ .Fn getnanotime "struct timespec *tsp" .Sh DESCRIPTION The +.Fn bintime +and +.Fn getbintime +functions store the system time as a +.Ft struct bintime +at the addresses specified by +.Fa bt . +The .Fn microtime and .Fn getmicrotime -functions store the system time as a +functions perform the same utility, but record the time as a .Ft struct timeval -at the address specified by -.Fa tv . -The +instead. +Similarly the .Fn nanotime and .Fn getnanotime -functions perform the same utility, but record the time as a -.Ft struct timespec -instead. +functions store the time as a +.Ft struct timespec . .Pp -.Fn Microtime +.Fn Bintime , +.Fn microtime , and .Fn nanotime always query the timecounter to return the current time as precisely as possible. Whereas -.Fn getmicrotime +.Fn getbintime , +.Fn getmicrotime , and .Fn getnanotime functions are abstractions which return a less precise, but faster to obtain, time. .Pp The intent of the -.Fn getmicrotime +.Fn getbintime , +.Fn getmicrotime , and .Fn getnanotime functions is to enforce the user's preference for timer accuracy versus execution time. .Sh SEE ALSO +.Xr binuptime 9 , +.Xr getbinuptime 9 , .Xr getmicrouptime 9 , .Xr getnanouptime 9 , .Xr microuptime 9 , @@ -86,13 +103,17 @@ execution time. .Xr tvtohz 9 .Sh HISTORY The +.Nm bintime +functions first appeared in +.Fx 5.0 . +The .Nm and .Nm nanotime functions first appeared in .Fx 3.0 but existed in other incarnations since -.Bx 4.4 +.Bx 4.4 . .Sh AUTHORS This manual page was written by .An Kelly Yancey Aq kbyanc@posi.net . diff --git a/share/man/man9/microuptime.9 b/share/man/man9/microuptime.9 index 304f205efc8c..3e0b6ac00b66 100644 --- a/share/man/man9/microuptime.9 +++ b/share/man/man9/microuptime.9 @@ -24,10 +24,12 @@ .\" .\" $FreeBSD$ .\" -.Dd January 3, 2000 +.Dd September, 16 2004 .Dt MICROUPTIME 9 .Os .Sh NAME +.Nm binuptime , +.Nm getbinuptime , .Nm microuptime , .Nm getmicrouptime , .Nm nanouptime , @@ -36,6 +38,10 @@ .Sh SYNOPSIS .In sys/time.h .Ft void +.Fn binuptime "struct bintime *bt" +.Ft void +.Fn getbinuptime "struct bintime *bt" +.Ft void .Fn microuptime "struct timeval *tv" .Ft void .Fn getmicrouptime "struct timeval *tv" @@ -45,40 +51,51 @@ .Fn getnanouptime "struct timespec *tsp" .Sh DESCRIPTION The +.Fn binuptime +and +.Fn getbinuptime +functions store the time elapsed since boot as a +.Ft struct bintime +at the address specified by +.Fa bt . +The .Fn microuptime and .Fn getmicrouptime -functions store the time elapsed since boot as a +functions perform the same utility, but record the elapsed time as a .Ft struct timeval -at the address specified by -.Fa tv . -The +instead. +Similarly the .Fn nanouptime and .Fn getnanouptime -functions perform the same utility, but record the elapsed time as a -.Ft struct timespec -instead. +functions store the elapsed time as a +.Ft struct timespec . .Pp -.Fn Microuptime +.Fn Binuptime , +.Fn microuptime , and .Fn nanouptime always query the timecounter to return the current time as precisely as possible. Whereas -.Fn getmicrouptime +.Fn getbinuptime , +.Fn getmicrouptime , and .Fn getnanouptime functions are abstractions which return a less precise, but faster to obtain, time. .Pp The intent of the -.Fn getmicrouptime +.Fn getbinuptime , +.Fn getmicrouptime , and .Fn getnanouptime functions is to enforce the user's preference for timer accuracy versus execution time. .Sh SEE ALSO +.Xr bintime 9 , +.Xr getbintime 9 , .Xr getmicrotime 9 , .Xr getnanotime 9 , .Xr microtime 9 , diff --git a/share/man/man9/time.9 b/share/man/man9/time.9 index a5bf9737f386..8153a8687f0d 100644 --- a/share/man/man9/time.9 +++ b/share/man/man9/time.9 @@ -31,113 +31,91 @@ .\" .\" $FreeBSD$ .\" -.Dd March 22, 1997 +.Dd September 17, 2004 .Dt TIME 9 .Os .Sh NAME +.In sys/time.h .Nm boottime , -.Nm mono_time , -.Nm runtime , -.Nm time +.Nm time_second , +.Nm time_uptime .Nd system time variables .Sh SYNOPSIS .Bl -item -compact .It .Va extern struct timeval boottime ; .It -.Va extern volatile struct timeval mono_time ; +.Va extern struct time_t time_second ; .It -.Va extern struct timeval runtime ; -.It -.Va extern struct timeval time ; +.Va extern struct timeval time_uptime ; .El .Sh DESCRIPTION The -.Va time -variable is the system's -.Dq wall time -clock. -It is set at boot by -.Xr inittodr 9 , -and is updated by the -.Xr settimeofday 2 -system call and by periodic clock interrupts. -.Pp -The .Va boottime variable holds the system boot time. -It is set from -.Va time -at system boot, and is updated when the system time is adjusted -with -.Xr settimeofday 2 . .Pp The -.Va runtime -variable holds the time that the system switched to the -current process. -It is set after each context switch, -and is updated when the system time is adjusted with -.Xr settimeofday 2 . -Because -.Va runtime -is used for system accounting, it is set with the high-resolution -.Xr microtime 9 -function, rather than being copied from -.Va time . +.Va time_second +variable is the system's +.Dq wall time +clock to the second. .Pp The -.Va mono_time -variable is a monotonically increasing system clock. -It is set -from -.Va time -at boot, and is updated by the periodic timer interrupt. -(It is -not updated by -.Xr settimeofday 2 . ) +.Va time_uptime variable is the number of seconds since boot. .Pp -All of these variables contain times -expressed in seconds and microseconds since midnight (0 hour), -January 1, 1970. -.Pp -Clock interrupts should be blocked -when reading or writing -.Va time -or -.Va mono_time , -because those variables are updated by -.Fn hardclock . The -.Xr gettime 9 -function can be used to read the -.Va time -variable in an atomic manner. -There is no equivalent function for accessing -.Va mono_time . +.Xr bintime 9, +.Xr getbintime 9 , +.Xr microtime 9 , +.Xr getmicrotime 9 , +.Xr nanotime 9 , +and +.Xr getnanotime 9 , +functions can be used to get the current time more accurately and in an +atomic manner. +Similarly, the +The +.Xr binuptime 9, +.Xr getbinuptime 9 , +.Xr microuptime 9 , +.Xr getmicrouptime 9 , +.Xr nanouptime 9 , +and +.Xr getnanouptime 9 , +functions can be used to get the time elapse since boot more accurately +and in an atomic manner. The .Va boottime -and -.Va runtime -variables may be read and written without special precautions. +variable may be read and written without special precautions. .Pp -It should be noted that due to the differences in how the time values -returned by -.Xr gettime 9 -and -.Xr microtime 9 -are updated, comparing the results of the two routines -may result in a time value that appears to go backwards. -This can be avoided by consistently using one function or the other -for use in any given context. .Sh SEE ALSO +.Xr clock_settime 2 , +.Xr ntp_adjtime 2 , .Xr settimeofday 2 , -.Xr gettime 9 , -.\" .Xr hardclock 9 , -.\" .Xr hz 9 , -.Xr inittodr 9 , -.Xr microtime 9 -.Sh BUGS -The notion of having a single -.Va runtime -variable obviously would not be appropriate in multiprocessor systems. +.Xr getbintime 9 , +.Xr getbinuptime 9 , +.Xr getmicrotime 9 , +.Xr getmicrouptime 9 , +.Xr getnanotime 9 , +.Xr getnanouptime 9 , +.Xr bintime 9 , +.Xr binuptime 9 , +.Xr microtime 9 , +.Xr microuptime 9 , +.Xr nanotime 9, +.Xr nanouptime 9 +.Rs +.%A "Poul-Henning Kamp" +.%T "Timecounters: Efficient and precise timekeeping in SMP kernels" +.%J "Proceedings of EuroBSDCon 2002" +.%C "Amsterdam" +.%O /usr/share/doc/papers/timecounter.ascii.gz +.Re +.Rs +.%A "Marshall Kirk McKusick" +.%A "George V. Neville-Neil" +.%B "The Design and Implementation of the FreeBSD Operating System" +.%D "July 2004" +.%I "Addison-Wesley" +.%P "57-61,65-66" +.Re