On 06/26/2018 09:03 AM, Arnd Bergmann wrote: > As Dave Chinner points out, we don't have a proper documentation for the > ktime_get() family of interfaces, making it rather unclear which of the > over 30 (!) interfaces one should actually use in a driver or elsewhere > in the kernel. > > I wrote up an explanation from how I personally see the interfaces, > documenting what each of the functions do and hopefully making it a bit > clearer which should be used where. > > This is the first time I tried writing .rst format documentation, so > in addition to any mistakes in the content, I probably also introduce > nonstandard formatting ;-) > > I first tried to add an extra section to > Documentation/timers/timekeeping.txt, but this is currently not included > in the generated API, and it seems useful to have the API docs as part > of what gets generated in > https://www.kernel.org/doc/html/latest/core-api/index.html#core-utilities > instead, so I started a new file there. > > I also considered adding the documentation inline in the > include/linux/timekeeping.h header, but couldn't figure out how to do > that in a way that would result both in helpful inline comments as > well as readable html output, so I settled for the latter, with > a small note pointing to it from the header. > > Cc: Dave Chinner <david@xxxxxxxxxxxxx> > Cc: John Stultz <john.stultz@xxxxxxxxxx> > Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx> > Cc: Stephen Boyd <sboyd@xxxxxxxxxx> > Cc: Linus Walleij <linus.walleij@xxxxxxxxxx> > Signed-off-by: Arnd Bergmann <arnd@xxxxxxxx> > --- > Documentation/core-api/index.rst | 1 + > Documentation/core-api/timekeeping.rst | 185 +++++++++++++++++++++++++++++++++ > include/linux/timekeeping.h | 15 +++ > 3 files changed, 201 insertions(+) > create mode 100644 Documentation/core-api/timekeeping.rst > > diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst > index f5a66b72f984..989c97cc232a 100644 > --- a/Documentation/core-api/index.rst > +++ b/Documentation/core-api/index.rst > @@ -28,6 +28,7 @@ Core utilities > printk-formats > circular-buffers > gfp_mask-from-fs-io > + timekeeping > > Interfaces for kernel debugging > =============================== > diff --git a/Documentation/core-api/timekeeping.rst b/Documentation/core-api/timekeeping.rst > new file mode 100644 > index 000000000000..97dafa69dddf > --- /dev/null > +++ b/Documentation/core-api/timekeeping.rst > @@ -0,0 +1,185 @@ > +ktime access > +============ I would prefer "ktime accessors" or "ktime interfaces", but no big deal. > + > +Device drivers can read the current time using ktime_get() and the many > +related functions declared in linux/timekeeping.h. As a rule of thumb, > +using an accessor with a shorter name is preferred over one with a longer > +name if both are equally fit for a particular use case. > + > +Basic ktime_t based interfaces > +------------------------------ > + > +The recommended simplest form returns an opaque ktime_t, with variants > +that return time for different clock references: > + > + > +.. c:function:: ktime_t ktime_get( void ) > + > + CLOCK_MONOTONIC > + > + Useful for reliable timestamps and measuring short time intervals > + accurately. Starts at system boot time but stops during suspend. > + > +.. c:function:: ktime_t ktime_get_boottime( void ) > + > + CLOCK_BOOTTIME > + > + Like ktime_get(), but does not stop when suspended. This can be > + used e.g. for key expiration times that need to be synchronized > + with other machines across a suspend operation. > + > +.. c:function:: ktime_t ktime_get_real( void ) > + > + CLOCK_REALTIME > + > + Returns the time in relative to the UNIX epoch starting in 1970 > + using the Coordinated Universal Time (UTC), same as gettimeofday() > + user space. This is used for all timestamps that need to > + persist across a reboot, like inode times, but should be avoided > + for internal uses, since it can jump backwards due to a leap > + second update, NTP adjustment settimeofday() operation from user > + space. > + > +.. c:function:: ktime_t ktime_get_clocktai( void ) > + > + CLOCK_TAI > + > + Like ktime_get_real(), but uses the International Atomic Time (TAI) > + reference instead of UTC to avoid jumping on leap second updates. > + This is rarely useful in the kernel. > + > +.. c:function:: ktime_t ktime_get_raw( void ) > + > + CLOCK_MONOTONIC_RAW > + > + Like ktime_get(), but runs at the same rate as the hardware > + clocksource without (NTP) adjustments for clock drift. This is > + also rarely needed in the kernel. > + > +nanosecond, timespec64, and second output > +------------------------------------- Documentation/core-api/timekeeping.rst:60: WARNING: Title underline too short. nanosecond, timespec64, and second output ------------------------------------- and that's the only sphinx error or warning that I see. Nice. Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> thanks, -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
