Suggestion - Configurable Source Clock Type for Line Event Timestamping

[Jack Winch <sunt.un.morcov@xxxxxxxxx>]

Hi Folks,

I recently noticed that in Linux 5.7, gpiolib was changed such that
line events are now timestamped using the system 'monotonic' clock
rather than the system realtime clock.  The rationale for this change
appears to be due to the major use-case of the line event timestamp
data in relation to the nature of the system realtime clock (which can
jump backwards or forwards in time due to adjustments by third-parties
- e.g., NTP or PTP clients, etc).

For most users of the line event timestamp value, the use of the
realtime clock could be problematic due to the potential for
chronological line events to receive timestamp values with a
non-chronological progression (resulting from adjustments being made
to the clock).  This could be the source of a number of bugs,
functional limitations and frustrations which was solved easily enough
by transitioning to the use of the system monotonic clock.  That being
said, I know there are users of the line event timestamp who actively
rely on that value being obtained from the system realtime clock.

My suggestion (which I would be happy to implement myself) is to allow
users to select the clock to be used for line event timestamping on a
per line handle basis.  The merit of this approach is that the
appropriate clock type may be selected on a per line handle basis
according to the needs of the user.  This of course has some
implications which are not desirable without merit, but may be deemed
acceptable in balance with the resultant functionality.  In summary,
these are:

1. Increase in processing overhead and latency of timestamp
acquisition on line event interrupts.  Implementing the proposed
change requires a function call to be made to the appropriate ktime
accessor function, based on what the user has configured as the
timestamp clock source.  In kernel versions from 5.7 to current, a
call is made to the ktime_get_ns() function which is most likely
inlined by the compiler.  This change will result in an actual jump
having to be made, which will have processor and memory access
overhead (potential I$ and D$ misses).  Then there is of course the
overhead of resolving which function to call - either a switch
statement or call by function pointer (probably the latter option).

2. Additions required to the userspace ABI.  Additional IOCTLs will be
required for line handles, allowing the source clock type for line
event timestamping to be get or set.

3. Additions required to libgpiod.  The existing API will have to be
added to in order to provide an abstraction for this new
functionality.  This requires changes to the core C library, as well
as the provided C++ and Python bindings (and their test cases).
Changes will also be required to the WiP libgpiod service and its
d-bus interface.  This change will also affect the proposed future
lightweight libgpiod service.

4. Documentation for both the GPIO subsystem and libgpiod will require
updating.  This should be done as part of the effort to implement this
functionality (if agreed upon) for the target version of the kernel
and libgpiod.

Such that applications now relying on the use of the 'monotonic'
system clock for timestamping line events do not require modification
after the implementation of this functionality (most applications), I
propose the 'monotonic' system clock be the default source clock.  If
the user wants to change this to another clock type, then they may do
so via the proposed additional IOCTLs and / or the proposed changes to
libgpiod.

I would be interested in hearing your thoughts on this suggestion / proposal.

~ Jack