 ___         _        _               _   ___ 
| _ \___ _ _| |_ __ _| |_ ___    __ _/ | |_  )
|  _/ _ \ '_|  _/ _` |  _/ _ \   \ V / |_ / / 
|_| \___/_|  \__\__,_|\__\___/    \_/|_(_)___|


INTRODUCTION
------------

	Everyone likes lights.  They're spiffy, catchy, and give an extra
personality to a perhaps otherwise boring item.  (Ever see those cars with
neon glowing from underneath?  Perfect example.)  Enter Portato.

	Portato is a simple program which can provide glitz (and can also be
extremely useful.)  It uses the parallel port in conjunction with attached
LEDs (or any low-current drawing 5V indicator) to provide status information
about your Linux box.  For those obsessed with knowing the status of things
at all times (as I sometimes am) this program can be a very good companion.
It can also be an excellent diagnostic tool.


FEATURES
--------

	Portato is configurable via the Portato config file.  Eight data
pins are available on the parallel port so you have eight lights to play
with.  Different types of system events, or combinations of those events
can be assigned to the individual lights.

Portato can monitor the following events:
	o user, system, nice, and idle cpu
	o hard drive activity
	o interrupts 1-15 (useful for monitoring keyboards, serial ports,
		ethernet cards, sound cards, drive controllers, and any
		other interrupt driven devices)
	o network receive, transmit, (or both), and collisions on any device
	o swap pages being brought in, out, or both

	Portato is designed to use as little of your cpu time as
possible.  It periodically checks values from the /proc filesystem (in
particular /proc/stat and /proc/net/dev) to determine if a specified
activity has occured (i.e. its value has changed since the last update).
You can designate in the configuration file how often these updates occur.
The bulk of the CPU time needed is for the system to open and close the
procfiles.  A good CPU cache scheme reduces the CPU time needed since most
of the time Portato is just spinning in its update loop.  Thus sporadic
activity on all of the lights will use the most CPU time.


INSTALLATION
------------

1)  Making the LEDs work may be the most difficult part.  It is a
    simple process, which if you have at least been exposed to hooking
    components together will be easy.  The data ports on the 25 pin parallel
    port connector are pins 2-9.  Run each of these pins through a 150 ohm
    resistor, then through an LED, to ground (pin 20).  If this is still
    unfamiliar take a look at the led-stat.txt file (included here).

2)  Edit the Makefile to reflect where you'd like the default config file
    and the portato binary.  Also add any compile-time options you want.

    Compile-time options in the Makefile:

    -DTESTCOMPILE  - compiles Portato with no parallel port output and reads
                     its files from the current directory rather than /proc.
                     this is good for testing and compiling the program on a
                     non-Linux box while at work.
    -DPROFILE      - makes Portato calculate how much CPU time it is using
                     for updates and writes it to stdout at shutdown
    -DDEBUG        - Portato will print out every event it is looking for and
                     lines, fields, and offsets of where it is making 16-bit
                     comparisons in the procfile (this is plenty verbose)

3)  type "make" - this will hopefully give you the portato binary

4)  type "make install" - this will copy portato to the BINDIR and the
                          configuration file to the CONFIGDIR

5)  Edit the configuration file (portato.conf) in CONFIGDIR to reflect what
    you'd like to monitor with Portato.  All of the options are explained
    in the sample file provided.  Portato will tell you if a config file line
    is bad but doesn't do a good job of telling you what's wrong with it so
    you'll have to figure that out yourself.


RUNNING
-------

	Portato takes one argument (the name of the configuration file).
If that argument is not provided it uses the configuration file located
in the CONFIGDIR specified in the Makefile.  Put "portato &" in your rc.local
if you'd like so you can use Portato all of the time.  (God I'm such a
cheez-ball sometimes).
	Note that if at start time a network device does not exist in
/proc/net/dev then portato will die with an error.  So make sure all devices
are loaded first if they're modules before starting portato.


CREDIT
------

	Thanks go to Joseph Vigneau (joev@wpi.edu) for his led-stat.txt
file which explains how to hook LEDs up to your parallel port and
damianf@wpi.edu for his port.h file which has functions for writing bytes
out to a port.


COPYING
-------

	You are free to use and modify this program as you see fit, so long
as you give credit for its use in derivative works.  You are not allowed to
use this code for any commercial venture (like you'd make money off of it
anyway).  Understand also that I am not responsible for damage to your
machine as a result of use of this program (though I don't suspect that
will be a problem as long as you don't use random port addresses) nor do I
claim that this program is useful in any way, shape, or form (though I think
it is).  If you would like to re-use or modify this code, please contact me
at the email address at the end of this document.


FUTURE
------

	I want to make Portato capable of driving huge banks of LEDs so
my Linux box can look like a 60's sci-fi film.  I would also like to be
able to get values directly from the kernel rather than parsing them.  The
proc filesystem keeps this program from being less cpu intensive than it is.
Please send ideas on what you'd like to see.


CHANGES
-------

v1.2 - optimizations - cleaned up inner loop in main_loop() - uses 16-bit
       compare rather than atoi() and 32-bit compare.  these optimizations
       appear to make portato 1.2 around 40% faster in procfile analysis
       than 1.1, but it's hard to judge
     - fixed intr 15 bug (where interrupt 15 would never be monitored)
     - can now specify lpt port or hexidecimal address
     - update rate specification more flexible
v1.1 - totally replaced updating function to reduce CPU overhead by
       storing absolute locations of each desired field and recalculating
       them only if procfile changes
     - added support for putting only base names of network devices to get
       all devices of that type, i.e. interface "ppp" gets ppp* devices
v1.0 - first working version of Portato (although it took almost no user
       CPU time, it evidently took somewhere around 2-3% of the system CPU
       on my test box largely because of many system calls)


WHY IS THIS PROGRAM CALLED PORTATO?
-----------------------------------

Why not?

If you're stuck, find undocumented features (slang term: bugs), or would
like to see new frills (slang term: features), feel free to send some email.

Peter (skIp) Heist (heistp@rpi.edu)
