• Arnd Bergmann's avatar
    Documentation: document ktime_get_*() APIs · 0e3fd810
    Arnd Bergmann authored
    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@fromorbit.com>
    Cc: John Stultz <john.stultz@linaro.org>
    Cc: Thomas Gleixner <tglx@linutronix.de>
    Cc: Stephen Boyd <sboyd@kernel.org>
    Tested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
    Reviewed-by: default avatarRandy Dunlap <rdunlap@infradead.org>
    Reviewed-by: default avatarLinus Walleij <linus.walleij@linaro.org>
    Signed-off-by: default avatarArnd Bergmann <arnd@arndb.de>
    Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
    0e3fd810
timekeeping.rst 7.08 KB