documentation work

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..2977c05
--- /dev/null
+++ b/README
@@ -0,0 +1,52 @@
+NetWatch!
+
+       This is NetWatch, a system for remote system-management-mode-based
+control of a machine without support from or awareness by the OS. It works by
+taking over a second network card to provide a standard VNC server, such that
+a machine elsewhere on the network can see the text or graphics console of the
+machine and inject keystrokes as needed.
+
+       <description of SMM and what we do with it>.
+
+       <benchmarks here>.
+
+       Because NetWatch is invisible to the OS, its CPU usage is difficult to
+monitor; we do so by comparing the MD5 throughput of the system with NetWatch
+running versus without. The only way that the OS could detect this performance
+drain is by spinning tightly and watching for a sudden jump in the CPU's time
+stamp counters.
+
+       Although it would be possible to start up NetWatch after an OS kernel
+has already loaded, it is easier and more useful to load it from GRUB before
+the OS boots, such that even the bootloader itself can be controlled over the
+network. We do this by providing a stub loader (grubload/) which can be invoked
+from GRUB, and takes care of loading the main NetWatch ELF image. Once this is
+done and NetWatch is up and running, the loader returns to real mode and
+reinvokes GRUB via the BIOS.
+
+       Our current development platform, the Intel ICH2, does not allow SMM
+traps on arbitrary PCI accesses. This makes stealing the network card from the
+OS somewhat difficult, since there is nothing SMM code can do to cleanly block
+access. NetWatch simply chooses its desired network card, and then repeatedly
+clobbers the PCI base address registers. Although Linux resets the BARs to sane
+values when it probes the PCI bus, by the time it attempts to actually load
+the network driver, the card will no longer be accessible; fortunately, the 
+driver quickly gives up, and Linux no longer attempts to access the card.
+
+       The northbridge can be configured to invoke a system management
+interrupt every 64 milliseconds, and so the bulk of NetWatch's work is done
+from this interrupt: checking the network card for incoming packets, invoking
+lwIP, and sending any response packets necessary. SMM entry also occurs when
+when the OS reads from the keyboard I/O ports, to inject scan codes as needed.
+
+       Much of NetWatch is very hardware-dependent, and although we've tried
+to maintain clean interface separation to allow for easy porting, the current
+implementation requires:
+
+  - Intel ICH2 system chipset
+  - 3C509 Ethernet card to be used by NetWatch, plus another card of
+    any type for the OS
+  - BIOS which does not set the D_LCK bit. Any system old enough to be
+    based on the ICH2 is very likely to have a suitable BIOS.
+
+       Current open issues are listed in the TODO file.

diff --git a/TODO b/TODO
index 7a77450856bd6e8dffe71c5a276c58cf7fb686ad..1892de9989f4b5b50f28237d109209b3928f07cc 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,22 +1,9 @@
-To do list:
-[ ] Spin the fans!
-    Requested by de0u 9/11/2008
-[ ] Twice weekly backup into AFS
-    Requested by de0u 9/11/2008
-[ ] Code & data size (kloc) for IP, and for VNC estimate / project
-    presentation
-    Requested by de0u 9/11/2008
-[ ] Fix ACPI (0xB2/B3 emulation -- can we fake it?)
-[.] PCI scan / module instantiation
-[.] Refactor smram_* 
-    First cut at splitting out ICH2 code done by jdpotter 9/12/2008
-    PCI scan can be done later
-[.] Update blog as needed
-[X] Refactor SMI management (moving it all out to an ich2/x.c would be fine
-    as pass 1 -- later it can use the PCI scan)
-[ ] Synchronize headers
-[ ] Fix build system...
-[X] Something has gone very wrong with the receive ring buffer, and on
-    occasion, the machine stops receiving forever.
-    fixed a few hours later...
-[ ] 'unknown TNT2 format ff', then a hang still happens on occasion
+Todo list as of 20081216:
+
+- Support formats other than RGB888
+- Support password-based (or better) VNC authentication.
+- Automatically switch GRUB from the loader to the actual kernel
+- Fix ridiculously slow video checksumming (i.e. make X usable)
+- Make ACPI work?
+- "Unknown TNT2 format ff" hang occasionally happens during startx
+- Figure out why traps cause lockup in SMM.