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            --------------------------------------------------------------------------
  6            
  7            
  8            What is emlog?
  9            ==============
 10            

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

 18 jelson 1.1 

 19 jelson 1.4 The emlog kernel module that implements simple character device

 20 jelson 1.1 driver.  The driver acts like a named pipe that has a finite, circular

 21 jelson 1.3 buffer.  The size of the buffer is easily configurable.  As more data
 22            is written into the buffer, the oldest data is discarded.  A process

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

 84 jelson 1.3    associated buffers.  This won't work until all emlog device files
 85               are closed.
 86            

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

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

158 jelson 1.1 
159            
160            Known Bugs
161            ==========
162            
163            emlog identifies buffers based on solely on the inode number of the
164            device file being accessed.  If two device files on two different

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

166 jelson 1.1 same buffer, as if they were the same device file.
167            

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

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

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