doc: document the event timestamps

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

doc/Makefile.am

@@ -27,6 +27,7 @@ header_files = \
 	$(srcdir)/tablet-support.dox \
 	$(srcdir)/tapping.dox \
 	$(srcdir)/test-suite.dox \
+	$(srcdir)/timestamps.dox \
 	$(srcdir)/tools.dox \
 	$(srcdir)/touchpad-jumping-cursors.dox \
 	$(srcdir)/touchpad-pressure.dox \

doc/page-hierarchy.dox

@@ -24,10 +24,11 @@
 
 - @subpage tablet-support
 
-@page general General setup
+@page general General 
 
 - @subpage udev_config
 - @subpage seats
+- @subpage timestamps
 
 @page misc Users
 

doc/timestamps.dox

@@ -0,0 +1,36 @@
+/**
+
+@page timestamps Timestamps
+
+@section event_timestamps Event timestamps
+
+Most libinput events provide a timestamp in millisecond and/or microsecond
+resolution. These timestamp usually increase monotonically, but libinput
+does not guarantee that this always the case. In other words, it is possible
+to receive an event with a timestamp earlier than the previous event. 
+
+For example, if a touchpad has @ref tapping enabled, a button event may have a
+lower timestamp than an event from a different device. Tapping requires the
+use of timeouts to detect multi-finger taps and/or @ref tapndrag.
+
+Consider the following event sequences from a touchpad and a mouse:
+
+<pre>
+Time      Touchpad      Mouse
+---------------------------------
+t1       finger down
+t2        finger up
+t3                     movement
+t4       tap timeout
+</pre>
+
+For this event sequence, the first event to be sent to a caller is in
+response to the mouse movement: an event of type @ref
+LIBINPUT_EVENT_POINTER_MOTION with the timestamp t3.
+Once the timeout expires at t4, libinput generates an event of 
+@ref LIBINPUT_EVENT_POINTER_BUTTON (press) with a timestamp t1 and an event
+@ref LIBINPUT_EVENT_POINTER_BUTTON (release) with a timestamp t2.
+
+Thus, the caller gets events with timestamps in the order t3, t1, t2,
+despite t3 > t2 > t1.
+*/

src/libinput.h

@@ -972,6 +972,9 @@ libinput_event_device_notify_get_base_event(struct libinput_event_device_notify
 /**
  * @ingroup event_keyboard
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -980,6 +983,9 @@ libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
 /**
  * @ingroup event_keyboard
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -1035,6 +1041,9 @@ libinput_event_keyboard_get_seat_key_count(
 /**
  * @ingroup event_pointer
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -1043,6 +1052,9 @@ libinput_event_pointer_get_time(struct libinput_event_pointer *event);
 /**
  * @ingroup event_pointer
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -1400,6 +1412,9 @@ libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
 /**
  * @ingroup event_touch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -1408,6 +1423,9 @@ libinput_event_touch_get_time(struct libinput_event_touch *event);
 /**
  * @ingroup event_touch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -1564,6 +1582,9 @@ libinput_event_touch_get_base_event(struct libinput_event_touch *event);
 /**
  * @ingroup event_gesture
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -1572,6 +1593,9 @@ libinput_event_gesture_get_time(struct libinput_event_gesture *event);
 /**
  * @ingroup event_gesture
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -2300,6 +2324,9 @@ libinput_event_tablet_tool_get_seat_button_count(struct libinput_event_tablet_to
 /**
  * @ingroup event_tablet
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet tool event
  * @return The event time for this event
  */
@@ -2309,6 +2336,9 @@ libinput_event_tablet_tool_get_time(struct libinput_event_tablet_tool *event);
 /**
  * @ingroup event_tablet
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet tool event
  * @return The event time for this event in microseconds
  */
@@ -2735,6 +2765,9 @@ libinput_event_tablet_pad_get_mode_group(struct libinput_event_tablet_pad *event
 /**
  * @ingroup event_tablet
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet pad event
  * @return The event time for this event
  */
@@ -2744,6 +2777,9 @@ libinput_event_tablet_pad_get_time(struct libinput_event_tablet_pad *event);
 /**
  * @ingroup event_tablet_pad
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet pad event
  * @return The event time for this event in microseconds
  */
@@ -2799,6 +2835,9 @@ libinput_event_switch_get_base_event(struct libinput_event_switch *event);
 /**
  * @ingroup event_switch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput switch event
  * @return The event time for this event
  */
@@ -2808,6 +2847,9 @@ libinput_event_switch_get_time(struct libinput_event_switch *event);
 /**
  * @ingroup event_switch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput switch event
  * @return The event time for this event in microseconds
  */