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

 87 jelson 1.3    associated buffers.  This won't work until all emlog device files
 88               are closed.
 89            

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

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

161 jelson 1.1 
162            
163            Known Bugs
164            ==========
165            

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

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

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

169 jelson 1.1 same buffer, as if they were the same device file.
170            

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

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

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