[v1] libcamera: controls: Clarify units of `FrameWallClock`
diff mbox series

Message ID 20250623081922.96900-1-barnabas.pocze@ideasonboard.com
State New
Headers show
Series
  • [v1] libcamera: controls: Clarify units of `FrameWallClock`
Related show

Commit Message

Barnabás Pőcze June 23, 2025, 8:19 a.m. UTC
The description of the control mentions SensorTimestamp multiple
times, but it omits that the two do not have the same units.
Clarify that.

Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
---

Or could it easily be converted to nanoseconds? Is there an overflow issue
in the ClockRecovery class in that case? What was the motivation for making
it μs? (I suppose nanosecond resolution is not that useful when synchronizing
across a network, etc?)

---
 src/libcamera/control_ids_core.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

--
2.50.0

Comments

Naushir Patuck June 23, 2025, 10:44 a.m. UTC | #1
Hi Barnabás,

Thanks for updating this.

On Mon, 23 Jun 2025 at 09:19, Barnabás Pőcze
<barnabas.pocze@ideasonboard.com> wrote:
>
> The description of the control mentions SensorTimestamp multiple
> times, but it omits that the two do not have the same units.
> Clarify that.
>
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>

Reviewed-by: Naushir Patuck <naush@raspberrypi.com>

> ---
>
> Or could it easily be converted to nanoseconds? Is there an overflow issue
> in the ClockRecovery class in that case? What was the motivation for making
> it μs? (I suppose nanosecond resolution is not that useful when synchronizing
> across a network, etc?)
>
> ---
>  src/libcamera/control_ids_core.yaml | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
> index 028919ef3..0708ec7cc 100644
> --- a/src/libcamera/control_ids_core.yaml
> +++ b/src/libcamera/control_ids_core.yaml
> @@ -1272,7 +1272,8 @@ controls:
>        description: |
>          This timestamp corresponds to the same moment in time as the
>          SensorTimestamp, but is represented as a wall clock time as measured by
> -        the CLOCK_REALTIME clock.
> +        the CLOCK_REALTIME clock. Note that this control measures time in units
> +        of microseconds as opposed to nanoseconds in case of SensorTimestamp.
>
>          Being a wall clock measurement, it can be used to synchronise timing
>          across different devices.
> --
> 2.50.0
Kieran Bingham June 23, 2025, 11:59 a.m. UTC | #2
Quoting Naushir Patuck (2025-06-23 11:44:54)
> Hi Barnabás,
> 
> Thanks for updating this.
> 
> On Mon, 23 Jun 2025 at 09:19, Barnabás Pőcze
> <barnabas.pocze@ideasonboard.com> wrote:
> >
> > The description of the control mentions SensorTimestamp multiple
> > times, but it omits that the two do not have the same units.
> > Clarify that.
> >
> > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> 
> Reviewed-by: Naushir Patuck <naush@raspberrypi.com>
> 
> > ---
> >
> > Or could it easily be converted to nanoseconds? Is there an overflow issue
> > in the ClockRecovery class in that case? What was the motivation for making
> > it μs? (I suppose nanosecond resolution is not that useful when synchronizing
> > across a network, etc?)

Would this be more beneficial for the accuracy of the sync algorithm?
(And also keep both timestamps 'aligned' for units usage?)

> >
> > ---
> >  src/libcamera/control_ids_core.yaml | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)
> >
> > diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
> > index 028919ef3..0708ec7cc 100644
> > --- a/src/libcamera/control_ids_core.yaml
> > +++ b/src/libcamera/control_ids_core.yaml
> > @@ -1272,7 +1272,8 @@ controls:
> >        description: |

Should we maybe have some sort of explicit units field on controls when
it makes sense?

> >          This timestamp corresponds to the same moment in time as the
> >          SensorTimestamp, but is represented as a wall clock time as measured by
> > -        the CLOCK_REALTIME clock.
> > +        the CLOCK_REALTIME clock. Note that this control measures time in units
> > +        of microseconds as opposed to nanoseconds in case of SensorTimestamp.
> >
> >          Being a wall clock measurement, it can be used to synchronise timing
> >          across different devices.
> > --
> > 2.50.0
Naushir Patuck June 23, 2025, 12:11 p.m. UTC | #3
On Mon, 23 Jun 2025 at 12:59, Kieran Bingham
<kieran.bingham@ideasonboard.com> wrote:
>
> Quoting Naushir Patuck (2025-06-23 11:44:54)
> > Hi Barnabás,
> >
> > Thanks for updating this.
> >
> > On Mon, 23 Jun 2025 at 09:19, Barnabás Pőcze
> > <barnabas.pocze@ideasonboard.com> wrote:
> > >
> > > The description of the control mentions SensorTimestamp multiple
> > > times, but it omits that the two do not have the same units.
> > > Clarify that.
> > >
> > > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> >
> > Reviewed-by: Naushir Patuck <naush@raspberrypi.com>
> >
> > > ---
> > >
> > > Or could it easily be converted to nanoseconds? Is there an overflow issue
> > > in the ClockRecovery class in that case? What was the motivation for making
> > > it μs? (I suppose nanosecond resolution is not that useful when synchronizing
> > > across a network, etc?)
>
> Would this be more beneficial for the accuracy of the sync algorithm?
> (And also keep both timestamps 'aligned' for units usage?)

No benefit wrt accuracy going from us to ns in the sync algorithm.
The only benefit would be to align the units for these two controls.
But, to be honest, I don't think that's such a big deal either.

Naush


>
> > >
> > > ---
> > >  src/libcamera/control_ids_core.yaml | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
> > > index 028919ef3..0708ec7cc 100644
> > > --- a/src/libcamera/control_ids_core.yaml
> > > +++ b/src/libcamera/control_ids_core.yaml
> > > @@ -1272,7 +1272,8 @@ controls:
> > >        description: |
>
> Should we maybe have some sort of explicit units field on controls when
> it makes sense?
>
> > >          This timestamp corresponds to the same moment in time as the
> > >          SensorTimestamp, but is represented as a wall clock time as measured by
> > > -        the CLOCK_REALTIME clock.
> > > +        the CLOCK_REALTIME clock. Note that this control measures time in units
> > > +        of microseconds as opposed to nanoseconds in case of SensorTimestamp.
> > >
> > >          Being a wall clock measurement, it can be used to synchronise timing
> > >          across different devices.
> > > --
> > > 2.50.0
Laurent Pinchart June 23, 2025, 12:38 p.m. UTC | #4
On Mon, Jun 23, 2025 at 12:59:49PM +0100, Kieran Bingham wrote:
> Quoting Naushir Patuck (2025-06-23 11:44:54)
> > On Mon, 23 Jun 2025 at 09:19, Barnabás Pőcze wrote:
> > >
> > > The description of the control mentions SensorTimestamp multiple
> > > times, but it omits that the two do not have the same units.
> > > Clarify that.
> > >
> > > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> > 
> > Reviewed-by: Naushir Patuck <naush@raspberrypi.com>
> > 
> > > ---
> > >
> > > Or could it easily be converted to nanoseconds? Is there an overflow issue
> > > in the ClockRecovery class in that case? What was the motivation for making
> > > it μs? (I suppose nanosecond resolution is not that useful when synchronizing
> > > across a network, etc?)
> 
> Would this be more beneficial for the accuracy of the sync algorithm?
> (And also keep both timestamps 'aligned' for units usage?)

I would really like to standardize on the same unit for all timestamps,
unless there's a compeling reason not to do so.

> > >
> > > ---
> > >  src/libcamera/control_ids_core.yaml | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
> > > index 028919ef3..0708ec7cc 100644
> > > --- a/src/libcamera/control_ids_core.yaml
> > > +++ b/src/libcamera/control_ids_core.yaml
> > > @@ -1272,7 +1272,8 @@ controls:
> > >        description: |
> 
> Should we maybe have some sort of explicit units field on controls when
> it makes sense?

That could be an interesting addition, but I'm not sure yet how useful
it would be in practice.

> > >          This timestamp corresponds to the same moment in time as the
> > >          SensorTimestamp, but is represented as a wall clock time as measured by
> > > -        the CLOCK_REALTIME clock.
> > > +        the CLOCK_REALTIME clock. Note that this control measures time in units
> > > +        of microseconds as opposed to nanoseconds in case of SensorTimestamp.
> > >
> > >          Being a wall clock measurement, it can be used to synchronise timing
> > >          across different devices.
Kieran Bingham June 23, 2025, 2:58 p.m. UTC | #5
Quoting Laurent Pinchart (2025-06-23 13:38:36)
> On Mon, Jun 23, 2025 at 12:59:49PM +0100, Kieran Bingham wrote:
> > Quoting Naushir Patuck (2025-06-23 11:44:54)
> > > On Mon, 23 Jun 2025 at 09:19, Barnabás Pőcze wrote:
> > > >
> > > > The description of the control mentions SensorTimestamp multiple
> > > > times, but it omits that the two do not have the same units.
> > > > Clarify that.
> > > >
> > > > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> > > 
> > > Reviewed-by: Naushir Patuck <naush@raspberrypi.com>
> > > 
> > > > ---
> > > >
> > > > Or could it easily be converted to nanoseconds? Is there an overflow issue
> > > > in the ClockRecovery class in that case? What was the motivation for making
> > > > it μs? (I suppose nanosecond resolution is not that useful when synchronizing
> > > > across a network, etc?)
> > 
> > Would this be more beneficial for the accuracy of the sync algorithm?
> > (And also keep both timestamps 'aligned' for units usage?)
> 
> I would really like to standardize on the same unit for all timestamps,
> unless there's a compeling reason not to do so.

I'd probably be on this side of the fence too ... it seems confusing to
me to have timestamps in different units in different places...

I wish I'd noticed that before I merged the control ;-(

--
Kieran


> 
> > > >
> > > > ---
> > > >  src/libcamera/control_ids_core.yaml | 3 ++-
> > > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > > >
> > > > diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
> > > > index 028919ef3..0708ec7cc 100644
> > > > --- a/src/libcamera/control_ids_core.yaml
> > > > +++ b/src/libcamera/control_ids_core.yaml
> > > > @@ -1272,7 +1272,8 @@ controls:
> > > >        description: |
> > 
> > Should we maybe have some sort of explicit units field on controls when
> > it makes sense?
> 
> That could be an interesting addition, but I'm not sure yet how useful
> it would be in practice.
> 
> > > >          This timestamp corresponds to the same moment in time as the
> > > >          SensorTimestamp, but is represented as a wall clock time as measured by
> > > > -        the CLOCK_REALTIME clock.
> > > > +        the CLOCK_REALTIME clock. Note that this control measures time in units
> > > > +        of microseconds as opposed to nanoseconds in case of SensorTimestamp.
> > > >
> > > >          Being a wall clock measurement, it can be used to synchronise timing
> > > >          across different devices.
> 
> -- 
> Regards,
> 
> Laurent Pinchart

Patch
diff mbox series

diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
index 028919ef3..0708ec7cc 100644
--- a/src/libcamera/control_ids_core.yaml
+++ b/src/libcamera/control_ids_core.yaml
@@ -1272,7 +1272,8 @@  controls:
       description: |
         This timestamp corresponds to the same moment in time as the
         SensorTimestamp, but is represented as a wall clock time as measured by
-        the CLOCK_REALTIME clock.
+        the CLOCK_REALTIME clock. Note that this control measures time in units
+        of microseconds as opposed to nanoseconds in case of SensorTimestamp.

         Being a wall clock measurement, it can be used to synchronise timing
         across different devices.