[libcamera-devel] [PATCH] libcamera: buffer: Improve timestamp documentation

[Umang Jain]

Hi Kieran,

On 8/28/20 5:25 PM, Kieran Bingham wrote:
> The Buffer timestamp documentation is short and does not explain that
> the timestamp is based on a monotonic time source, as opposed to the
> real/wall-time clocks available in the system.
>
> Expand upon the statements to detail that it can not be used directly as
> a wall-clock for the captured date/time without a further reference
> point, and that by taking a reference point - the user will be bringing
> in potential inconsistencies which must be considered.
>
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> ---
>   src/libcamera/buffer.cpp | 8 +++++++-
>   1 file changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/src/libcamera/buffer.cpp b/src/libcamera/buffer.cpp
> index a094737d0392..c08ca4234b29 100644
> --- a/src/libcamera/buffer.cpp
> +++ b/src/libcamera/buffer.cpp
> @@ -92,7 +92,13 @@ LOG_DEFINE_CATEGORY(Buffer)
>    * The timestamp is expressed as a number of nanoseconds relative to the system
>    * clock since an unspecified time point.
>    *
> - * \todo Be more precise on what timestamps refer to.
> + * This timestamp is monotonic and not affected by changes in system time,
> + * however it is still susceptible to small adjustments made by NTP.
> + *
> + * This clock has no specification on its time base, so can not be directly be
> + * converted to a 'real' wall clock time without a comparable reference point.
> + * However, continued conversions from the reference point, may bring in
> + * inaccuracies due to changes on the real time clock which must be considered.
>    */
>   
>   /**
Well, I just read clock_gettime manpage a while ago, so that context
helps me inferring this documentation more clearly. ;-)

Would it help pointing to that manpage as a "See also" for reference?

Anyways,

Reviewed-by: Umang Jain <email at uajain.com>