[PATCH libinput] timer: change the timer offset warning to a client bug

[Peter Hutterer]

This looks like a libinput bug (well, it does say "libinput bug" on the
package) but it hasn't been that for a long time. The cause is almost always
insufficient motivation to call libinput_dispatch() by the caller, or at least
not doing it with the celerity libinput demands (and deserves, if I may say
so).

Up-, down- or side-grade it to a client bug, so the outrage can be
directed elsewhere, preferably away from me. And add a section to the
documentation, just in case someone actually reads this stuff.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 doc/faqs.dox | 22 ++++++++++++++++++++++
 src/timer.c  |  8 ++++----
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/doc/faqs.dox b/doc/faqs.dox
index f0d85859..d5190926 100644
--- a/doc/faqs.dox
+++ b/doc/faqs.dox
@@ -198,4 +198,26 @@ href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev
 hwdb</a> or patches that include a change to the hwdb. See @ref hwdb for
 details on the hwdb and how to modify it locally.
 
+ at section faq_timer_offset What causes the "timer offset negative" warning?
+
+libinput relies on the caller to call libinput_dispatch() whenever data is
+available on the epoll-fd. Doing so will process the state of all devices
+and can trigger some timers to be set (e.g. palm detection, tap-to-click,
+disable-while-typing, etc.). Internally, libinput's time offsets are always
+based on the event time of the triggering event.
+
+For example, a touch event with time T may trigger a timer for the time T +
+180ms. When setting a timer, libinput checks the wall clock time to ensure
+that this time T + offset is still in the future. If not, the warning is
+logged.
+
+When this warning appears, it simply means that too much time has passed
+between the event occuring (and the epoll-fd triggering) and the current
+time. In almost all cases this is an indication of the caller being
+overloaded and not handling events as speedily as required.
+
+The warning has no immediate effect on libinput's behavior but some of the
+functionality that relies on the timer may be impeded (e.g. palms are not
+detected as they should be).
+
 */
diff --git a/src/timer.c b/src/timer.c
index f8de6662..584673a0 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -86,10 +86,10 @@ libinput_timer_set_flags(struct libinput_timer *timer,
 	uint64_t now = libinput_now(timer->libinput);
 	if (expire < now) {
 		if ((flags & TIMER_FLAG_ALLOW_NEGATIVE) == 0)
-			log_bug_libinput(timer->libinput,
-					 "timer %s: offset negative (-%dms)\n",
-					 timer->timer_name,
-					 us2ms(now - expire));
+			log_bug_client(timer->libinput,
+				       "timer %s: offset negative (-%dms)\n",
+				       timer->timer_name,
+				       us2ms(now - expire));
 	} else if ((expire - now) > ms2us(5000)) {
 		log_bug_libinput(timer->libinput,
 			 "timer %s: offset more than 5s, now %d expire %d\n",
-- 
2.14.3