From: Joshua Wise Date: Sat, 10 Oct 2009 21:00:00 +0000 (-0400) Subject: Rewrap README and GUIDE. X-Git-Url: http://git.joshuawise.com/netwatch.git/commitdiff_plain/22e3f1d996dfe075b62cc64283bc3c887bd9a146 Rewrap README and GUIDE. --- diff --git a/GUIDE b/GUIDE index 51aedd6..6e6e6d0 100644 --- a/GUIDE +++ b/GUIDE @@ -1,61 +1,56 @@ File overview: -elfload/ - Obsolete Linux-based ELF loader. This used to allow loading NetWatch -from within an already-running kernel; it could be updated to work with the -current memory layout, but is nonfunctional at the moment. See grubload/ for -the preferred loader. - grubload/ - This is a multiboot-compliant simple ELF loader, for use with NetWatch -aseg.elf images or similar. It loads its input file (passed via multiboot), -invokes the startup routines, and then returns to real mode and starts the -bootloader again. + A multiboot-compliant simple ELF loader, for use with NetWatch aseg.elf + images or similar. It loads its input file (passed via multiboot), + invokes the startup routines, and then returns to real mode and starts the + bootloader again. ich2/ - Intel ICH2 northbridge drivers. A similar API should be implemeted to -port NetWatch to other chipsets. + Intel ICH2 northbridge/southbridge drivers. A similar API should be + implemented to port NetWatch to other chipsets. ich7/ - Intel ICH7 northbridge drivers. Incomplete / untested. + Intel ICH7 northbridge drivers. Incomplete. include/ - General header files. + General header files. lib/ - Library functions. + Library functions. lwip/ - LWIP. (http://www.sics.se/~adam/lwip/) + LWIP. (http://www.sics.se/~adam/lwip/) net/ - Network card (currently only 3c90x) drivers, glue code, and the RFB -and HTTP applications. Other network drivers should go here. + Network card (currently only 3c90x) drivers, glue code, and the RFB and + HTTP applications. Other network drivers and applications should go here. netwatch/ - Main startup and initialization code, logging, SMI response, VGA text -overlay, and other general top-level sources. To build the main NetWatch binary, -run "make" here to produce aseg.elf. + Main startup and initialization code, logging, SMI response, VGA text + overlay, and other general top-level sources. To build the main NetWatch + binary, run "make" here to produce aseg.elf. pci/ - PCI bus interface and BAR-clobbering routines. + PCI bus interface and BAR-clobbering routines. tools/ - Assorted useful Linux command line tools we've found useful, such as -for SMRAM segment manipulation, raw I/O port pokes, etc. These are not required -to use NetWatch. + Assorted useful Linux command line tools we've found useful, such as for + SMRAM segment manipulation, raw I/O port pokes, etc. These are not + required to use NetWatch. video/ - Framebuffer drivers for VGA text and TNT2 graphics consoles. Supporting -graphics on other chipsets will require making a driver like that in tnt2.c. + Framebuffer drivers for VGA text and TNT2 graphics consoles. Supporting + graphics on other chipsets will require writing a driver similar to that + in tnt2.c. --- Porting NetWatch to other systems will likely require: -- A network driver, if you don't have a 3c905 (net/3c90x.c) -- A video driver, if you are interested in graphics rather than VGA text, - and don't have an NVidia TNT2. (video/tnt2.c) -- North- and southbridge drivers for your chipset. (ich2/) + - A network driver, if you don't have a 3c905 (net/3c90x.c) + - A video driver, if you are interested in graphics rather than VGA text, + and don't have an NVidia TNT2. (video/tnt2.c) + - North- and southbridge drivers for your chipset. (ich2/) We have found that Intel generally provides easily-accessible chipset datasheets on their website; searching for a particular ICH series part on diff --git a/README b/README index a673c33..6610c47 100644 --- a/README +++ b/README @@ -1,60 +1,61 @@ 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. - - System management mode, introduced with the 386SL, essentially allows -system driver code to run outside of OS control, caused by a special interrupt -pin on the CPU. This was originally intended for applications such as laptop -fan control; it is also the mechansim by which USB legacy keyboard emulation -occurs. When a system management interrupt occurs, the northbridge remaps -portions of memory to expose previously-hidden code, and asserts an SMI# signal, -causing the CPU to save all its state into system management RAM and vector to -a magic entry point. - - This is somewhat slow, and so there is a moderate performance impact -caused by running NetWatch, more significant when a VNC session is open. -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 +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. + +System management mode, introduced with the 386SL, essentially allows system +driver code to run outside of OS control, caused by a special interrupt pin +on the CPU. This was originally intended for applications such as laptop +fan control; it is also the mechanism by which USB legacy keyboard emulation +occurs. When a system management interrupt occurs, the northbridge remaps +portions of memory to expose previously-hidden code, and asserts an SMI# +signal, causing the CPU to save all its state into system management RAM and +vector to a magic entry point. + +This is somewhat slow, and so there is a moderate performance impact caused +by running NetWatch, more significant when a VNC session is open. 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 + * 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 + * 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. See GUIDE for an -overview of which source files do what. +Current open issues are listed in the TODO file. See GUIDE for an overview +of which source files do what.