1 jelson 1.1 emlog -- the EMbedded-system LOG-device
  2            Jeremy Elson - 6 June 2000

  3 jelson 1.3 jelson@circlemud.org

  4 jelson 1.1 

  5 jelson 1.5 Emlog web page:
  6            http://www.circlemud.org/~jelson/software/emlog
  7            

  8 jelson 1.1 --------------------------------------------------------------------------
  9            
 10            
 11            What is emlog?
 12            ==============
 13            

 14 jelson 1.4 emlog is a Linux kernel module that makes it easy to access the most
 15            recent (and *only* the most recent) output from a process.  It works
 16            just like "tail -f" on a log file, except that the storage required
 17            never grows.  This can be useful in embedded systems where there isn't
 18            enough memory or disk space for keeping complete log files, but the
 19            most recent debugging messages are sometimes needed (e.g., after an
 20            error is observed).

 21 jelson 1.1 

 22 jelson 1.6 The emlog kernel module implements simple character device driver.
 23            The driver acts like a named pipe that has a finite, circular buffer.
 24            The size of the buffer is easily configurable.  As more data is
 25            written into the buffer, the oldest data is discarded.  A process that
 26            reads from an emlog device will first read the existing buffer, then
 27            see new text as it's written, similar to monitoring a log file using
 28            "tail -f".

 29 jelson 1.1 

 30 jelson 1.7 emlog is free software, distributed under the GNU Public License
 31            (GPL); see the file COPYING for details.
 32            

 33 jelson 1.1 
 34            How is emlog used?
 35            ==================
 36            
 37            1: Configure, compile, and install emlog
 38            
 39               First, decide which major number you would like to use for emlog.
 40               This is configured in emlog.h using the constant
 41               EMLOG_MAJOR_NUMBER.  The default is 241, which is in the
 42               "local/experimental use" range according to the kernel
 43               documentation (similar to the 10/8 or 192.168/16 IP networks).
 44               Setting the major number to 0 will cause the kernel to dynamically
 45               assign a major number to emlog.
 46            
 47               Next, compile using the Makefile provided.  Typing 'make' should
 48               generate a single object file, 'emlog.o'.  Insert the module into
 49               the kernel using the 'insmod' command; e.g. 'insmod emlog.o'.
 50            
 51            2: Create device files for emlog
 52            
 53               Next, you must use 'mknod' to create device files that your
 54 jelson 1.1    processes can write to.  The major number of the device files
 55               should be whatever number you selected in Step 1 (e.g., 241).  The
 56               minor number is used to indicate the *size* of the ring buffer for
 57               that device file, specified as the the number of kilobytes (e.g.,
 58               1024 bytes).  For example, to create an 8K buffer called 'testlog':
 59            
 60               % mknod /tmp/testlog c 241 8
 61            
 62               You can create as many devices as you like.  Internally, emlog uses
 63               the file's inode number to identify which buffer it refers to.
 64            
 65            3: Write to and read from your new device file
 66            
 67               Once the device file has been created, simply write to your device
 68               file as you would any normal named pipe, e.g.
 69            
 70               % echo hello > /tmp/testlog
 71            
 72               Writes will never block because the buffer never runs out of space;
 73               old data is simply overwritten by new data.
 74            
 75 jelson 1.1    You can read from the log in the normal way, e.g. using cat.  Note
 76               that reads block, just like "tail -f", waiting for new log data.
 77               For example:
 78            
 79               % cat /tmp/testlog
 80               hello  [we immediately see the hello that we wrote in the previous step]
 81               _      [... and here's the cursor.  the 'cat' process is now
 82                       blocked, waiting for new input.  New data will be displayed
 83                       as it is written to the device by other processes.]
 84               ^C     [use control-c, for example, to stop reading.]
 85            
 86            
 87            4: Remove emlog when you're done
 88            
 89               Type 'rmmod emlog' will remove the emlog kernel module and free all

 90 jelson 1.3    associated buffers.  This won't work until all emlog device files
 91               are closed.
 92            

 93 jelson 1.1 
 94            
 95            Other Usage Notes
 96            =================
 97            
 98            emlog will allocate a fixed-size buffer on behalf of a device file if
 99            one of the following two conditions is true:
100            
101              1-  A process has the file open for reading or writing
102              2-  A process has written text to the pipe that has not been read
103            
104            In other words, buffers are persistent, even after a process closes
105            the pipe.  If another process later reads the pipe, the text will
106            still be there.  Note that it is possible (naturally) to fill virtual
107            memory by creating many such pipes, writing to all of them, and never
108            reading the data out of them.  All buffers will be freed when the
109            emlog kernel module is removed.
110            
111             
112            Troubleshooting
113            ===============
114 jelson 1.1 
115            Q:  When I try insert the module using 'insmod', I get 'I/O error".
116            
117            A:  That probably means the major device number being registered by
118            emlog is already in use by another device driver.  Try changing the
119            major device number in emlog.h (or, change it to 0 in order to get a
120            dynamically assigned major number).
121            
122            
123            Q: I'm seeing "I/O error" at a time *other* then when the module is
124            inserted.
125            
126            A:  Oops - you've found a bug in emlog.  Please report it.
127            
128            
129            Q:  When I try to access an emlog device file for reading or writing,
130            I get the error "no such device".
131            
132            A: This probably means either that the emlog kernel module is not
133            loaded; or, that the major number of the device file does not match
134            the major number that emlog registered.  To see which major number is
135 jelson 1.1 being used by emlog, type 'cat /proc/devices | grep emlog'.
136            
137            
138            Q:  When I try to access an emlog device file for reading or writing,
139            I get the error "invalid argument".
140            
141            A:  The *minor* number of the emlog device file must be a number
142            between 1 and 128, representing the number of kilobytes (1,024 bytes)
143            that should be used for emlog's ring buffer.  Make sure you're
144            specifying a valid minor number in your 'mknod' statement.
145            
146            
147            Q: I see "no memory" errors when I try opening new emlog files.
148            

149 jelson 1.3 A: Looks like you're out of virtual memory, sport.
150            
151            
152            Q: When I try to remove the emlog driver ("rmmod emlog"), I get the
153            error "Device or resource busy".
154            
155            A: That means a process is currently using an emlog device.  You have
156            to wait until all processes close all emlog device files until the
157            driver can be removed.  Try using "lsof" to see which files are in use
158            by which processes.
159            
160            
161            Q: You've made my computer crash.
162            
163            A: Sorry.  If you can reproduce the problem I'll try to fix it.

164 jelson 1.1 
165            
166            Known Bugs
167            ==========
168            

169 jelson 1.6 emlog identifies buffers based solely on the inode number of the

170 jelson 1.1 device file being accessed.  If two device files on two different

171 jelson 1.3 filesystems happen to have the same inode number, they will share the

172 jelson 1.1 same buffer, as if they were the same device file.
173            

174 jelson 1.3 Currently, the poll() function for emlog files is unimplemented.
175            Therefore, using the select() function with an emlog file will not
176            work.  (However, non-blocking reads DO work, e.g. by setting
177            O_NONBLOCK using ioctl()).
178            
179            Bug reports, patches, complaints, praise, and submissions of Central
180            Services Form 27B/6, are welcomed by the author (Jeremy Elson,
181            <jelson@circlemud.org>.

182 jelson 1.1 
183            
184            Who wrote emlog, and why?
185            =========================
186            
187            Emlog was written by Jeremy Elson <jelson@circlemud.org> at the
188            University of Southern California's Information Sciences Institute as
189            part of the SCADDS project <http://www.isi.edu/scadds>.  SCADDS is an
190            embedded systems research project.  We use small PC/104-bus-based
191            single-board-PCs using Linux.  We wanted to save the debugging output
192            from certain processes, but since these things have 16MB of disk space
193            and 32MB of RAM, keeping complete log files was not an option.  These
194            tiny nodes do have serial ports running PPP, though, so it's possible
195            to walk over to a node with a laptop, plug in a serial cable, and then
196            telnet into the box.  Using emlog, we can always keep the most recent
197            debug messages from our processes; in case of an error, we can plug in
198            a debug console and see what went wrong.
199            

200 jelson 1.3 This work was supported by DARPA under grant No. DABT63-99-1-0011 as
201            part of the SCADDS project, and was also made possible in part due to
202            support from Cisco Systems.
203