[PATCH] Add explanation of udelay() inaccuracy

[Russell King <rmk+kernel@armlinux.org.uk>]

There seems to be some misunderstanding that udelay() and friends will
always guarantee the specified delay.  This is a false understanding.
When udelay() is based on CPU cycles, it can return early for many
reasons which are detailed by Linus' reply to me in a thread in 2011:

  http://lists.openwall.net/linux-kernel/2011/01/12/372

However, a udelay test module was created in 2014 which allows udelay()
to only be 0.5% fast, which is outside of the CPU-cycles udelay()
results I measured back in 2011, which were deemed to be in the "we
don't care" region.

test_udelay() should be fixed to reflect the real allowable tolerance
on udelay(), rather than 0.5%.

Cc: David Riley <davidriley@chromium.org>
Cc: John Stultz <john.stultz@linaro.org>
Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
---
The issue of "udelay being too slow" came up towards the end of last
year again, caused again by people believing that udelay() should
provide a delay of at least the requested value.  We need to make sure
that the inaccuracies in this interface are well documented and
understood, and that we don't lead people down the path of believing
(through the addition of this test_udelay code) that udelay() is more
accurate than it really is. 0.5% is way _too_ tight a specification,
and as timer interrupt handling gets heavier, so the inaccuracy in the
CPU cycles based udelay() gets bigger.

 include/linux/delay.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/include/linux/delay.h b/include/linux/delay.h
index a6ecb34cf547..2ecb3c46b20a 100644
--- a/include/linux/delay.h
+++ b/include/linux/delay.h
@@ -5,6 +5,17 @@
  * Copyright (C) 1993 Linus Torvalds
  *
  * Delay routines, using a pre-computed "loops_per_jiffy" value.
+ *
+ * Please note that ndelay(), udelay() and mdelay() may return early for
+ * several reasons:
+ *  1. computed loops_per_jiffy too low (due to the time taken to
+ *     execute the timer interrupt.)
+ *  2. cache behaviour affecting the time it takes to execute the
+ *     loop function.
+ *  3. CPU clock rate changes.
+ *
+ * Please see this thread:
+ *   http://lists.openwall.net/linux-kernel/2011/01/09/56
  */
 
 #include <linux/kernel.h>
-- 
2.7.4