[PATCH] m68k/mac: Improve clocksource driver commentary

[Finn Thain]

qemu-system-m68k -M q800 has an old bug that causes the kernel to
occasionally complain about a soft lockup:

    watchdog: BUG: soft lockup - CPU#0 stuck for 5107s!

There isn't any actual lockup. The via1 clocksource produced a large
jump in jiffies, causing the watchdog to detect a stale timestamp.

The 32-bit clocksource counter runs at 783360 Hz and its period is
about 5482 seconds. Applying the "nanosecond" approximation used in
get_timestamp() in kernel/watchdog.c then yields the duration reported
in the log message above (always 5107 or 5108 in my tests):

0xffffffff / VIA_CLOCK_FREQ * 10**9 / 2**30 = 5106.209 seconds

It is notoriously difficult to correctly emulate a MOS6522 VIA chip. So
it seems wise to document the VIA clocksource driver better, especially
those hardware behaviours which the kernel relies upon.

Cc: Joshua Thompson <funaho@xxxxxxxxx>
Signed-off-by: Finn Thain <fthain@xxxxxxxxxxxxxx>
---
 arch/m68k/mac/via.c | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/arch/m68k/mac/via.c b/arch/m68k/mac/via.c
index 01e6b0e37f8d..142c2ed77c84 100644
--- a/arch/m68k/mac/via.c
+++ b/arch/m68k/mac/via.c
@@ -621,6 +621,22 @@ static u64 mac_read_clk(struct clocksource *cs)
 	 * These problems are avoided by ignoring the low byte. Clock accuracy
 	 * is 256 times worse (error can reach 0.327 ms) but CPU overhead is
 	 * reduced by avoiding slow VIA register accesses.
+	 *
+	 * The VIA timer counter observably decrements to 0xFFFF before the
+	 * counter reload interrupt gets raised. That complicates things a bit.
+	 *
+	 * State | vT1CH      | VIA_TIMER_1_INT | inference drawn
+	 * ------+------------+-----------------+-----------------------------
+	 *  A    | FE thru 00 | false           | counter is decrementing
+	 *  B    | FF         | false           | counter wrapped
+	 *  C    | FF         | true            | wrapped, interrupt raised
+	 *  D    | FF         | false           | wrapped, interrupt handled
+	 *  E    | FE thru 00 | true            | wrapped, interrupt unhandled
+	 *
+	 * State D is never observed because handling the interrupt involves
+	 * a 6522 register access and every access consumes a "phi 2" clock
+	 * cycle. So 0xFF implies either state B or C, depending on the value
+	 * of the VIA_TIMER_1_INT bit.
 	 */
 
 	local_irq_save(flags);
-- 
2.45.3