# HG changeset patch
# User Thinker K.F. Li <thinker@branda.to>
# Date 1215504384 -28800
# Node ID 5a281ce7453cc5c9e63fb40f8049ae4a788d3b9c
# Parent  76ce6e6624b8e48e6752bc3eb26ea75a68ef68d9
Add comments

diff -r 76ce6e6624b8 -r 5a281ce7453c vordog.c
--- a/vordog.c	Tue Jul 08 14:41:47 2008 +0800
+++ b/vordog.c	Tue Jul 08 16:06:24 2008 +0800
@@ -155,9 +155,13 @@
     .d_name = "vordog",
 };
 
-/* Implements watchdog(9) compatible driver. */
+/*
+ * Implements watchdog(9) compatible driver.
+ */
+/*! \brief Initialize timer for an interval in specified seconds.
+ */
 static int
-vordog_wd9_init(int timeout) {
+vordog_wd9_init(u_int timeout) {
     int val;
 
     if(timeout < 0 || timeout > 255)
@@ -169,27 +173,50 @@
     return 0;
 }
 
+/*! \brief Reset timer before it is timeout.
+ *
+ * It make the timer reload it's value from initial value register.
+ */
 static void
 vordog_wd9_reset(void) {
     outb(VD_STATUS, 0xc0);
 }
 
+/*! \brief Stop counting of watchdog timer.
+ */
 static void
 vordog_wd9_disable(void) {
     outb(VD_CTR, 0);
     outb(VD_STATUS, 0xc0);
 }
 
+/*! \brief event handler for watchdog(9).
+ *
+ * Timeout interval of watchdog(9) is defined by power of 2 nanoseconds.
+ * Watchdog timer of Vortex86 provides only small range of intervals.
+ * We use only the timer in seconds to simplize the code.  It provides
+ * interval 1~255 seconds.
+ *
+ * Since, only SFTMR1_STS is work, in my experience, and it is triggered
+ * after 4 times of initial value.  So, it only (i * 4) seconds in range
+ * of 4 ~ (255 * 4), where i is one of positive integer, are supported.
+ *
+ * The supported time intervals of watchdog(9) are 2^31~2^39 nanoseconds.
+ * vordog used a (i * 4) seconds for 2^n seconds while i * 4 seconds is
+ * smallest one of intervals that bigger than 2^n seconds.
+ */
 static void
-vordog_wd9_evh(void *private, u_int cmd, int *error) {
+vordog_wd9_evh(void *priv_data, u_int cmd, int *error) {
     vd_softc_t sc;
     u_int timeout, u;
+    /* 2^31, 2^32, ..., 2^39 nanoseconds */
     static const int timeouts[] = { 1, 2, 3, 5, 9, 18, 35, 69, 138};
 
-    sc = (vd_softc_t)private;
+    sc = (vd_softc_t)priv_data;
 
     u = cmd & WD_INTERVAL;
     if(u < 31 || u > 39) {
+	/* Out of range! Can not be configured. */
 	vordog_wd9_disable();
 	sc->init_val = 0;
 	return;