___ _ _ _ ___ | _ \___ _ _| |_ __ _| |_ ___ __ _/ | |_ ) | _/ _ \ '_| _/ _` | _/ _ \ \ 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)