# Clock Transformations

## Overview

[Clock objects](https://fuchsia.dev/docs/reference/kernel_objects/clock) represent functions which map all of the
points on a reference clock timeline to all of the points on the clock object's
timeline. Over all time, this function is represented as a
[piecewise linear function](https://en.wikipedia.org/wiki/Piecewise_linear_function).
Each segment of this function is a one dimensional
[affine transformation](https://en.wikipedia.org/wiki/Affine_transformation)
which relates the reference timeline to the clock's timeline.

Clock objects store only the most recent segment of the transformation at any
given time, not the entire history.

## Definition of the Affine Transformation

A segment of the piecewise linear function is stored using four numbers.

- The offset on the reference timeline *R~off~* (64 bits)
- The offset on the clock timeline *C~off~* (64 bits)
- The ratio of the reference to clock rate (*R~rate~* /*C~rate~*) (32/32 bits)

Given a reference time *r* , the function to apply the most recent segment of the
transformation, *C(r)* is given as

*C(r) = (((r - R~off~) \* C~rate~) / R~rate~) + C~off~*

Given a clock time *c* , the inverse of the *C* may be used to compute the
corresponding time on the reference timeline *r*.

*C^-1^(c) = r = (((c - C~off~) \* R~rate~) / C~rate~) + R~off~*

Care should be taken to avoid overflow when scaling the offset values. It is
recommended to store the intermediate result of multiplication in 96 bits before
dividing back down to something which will fit in 64 bits.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/concepts/kernel/clock_transformations.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/concepts/kernel/clock_transformations.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/concepts/kernel/clock_transformations.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/concepts/kernel/clock_transformations.md "Edit the source code of this page")