1 jelson 1.1 emlog -- the EMbedded-system LOG-device
|
2 jelson 1.14 Jeremy Elson - 1 March 2001
|
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.12 Version 0.30 of emlog (released March 1, 2001) should work under just
|
31 jelson 1.14 about any Linux kernel in the 2.x series, including 2.4.
|
32 jelson 1.12
|
33 jelson 1.8 emlog is free software, distributed under the GNU General Public
34 License (GPL); see the file COPYING for details.
|
35 jelson 1.7
|
36 jelson 1.1
37 How is emlog used?
38 ==================
39
40 1: Configure, compile, and install emlog
41
42 First, decide which major number you would like to use for emlog.
43 This is configured in emlog.h using the constant
44 EMLOG_MAJOR_NUMBER. The default is 241, which is in the
45 "local/experimental use" range according to the kernel
46 documentation (similar to the 10/8 or 192.168/16 IP networks).
47 Setting the major number to 0 will cause the kernel to dynamically
48 assign a major number to emlog.
49
50 Next, compile using the Makefile provided. Typing 'make' should
51 generate a single object file, 'emlog.o'. Insert the module into
52 the kernel using the 'insmod' command; e.g. 'insmod emlog.o'.
53
54 2: Create device files for emlog
55
56 Next, you must use 'mknod' to create device files that your
57 jelson 1.1 processes can write to. The major number of the device files
58 should be whatever number you selected in Step 1 (e.g., 241). The
59 minor number is used to indicate the *size* of the ring buffer for
60 that device file, specified as the the number of kilobytes (e.g.,
61 1024 bytes). For example, to create an 8K buffer called 'testlog':
62
63 % mknod /tmp/testlog c 241 8
64
65 You can create as many devices as you like. Internally, emlog uses
66 the file's inode number to identify which buffer it refers to.
67
68 3: Write to and read from your new device file
69
70 Once the device file has been created, simply write to your device
71 file as you would any normal named pipe, e.g.
72
73 % echo hello > /tmp/testlog
74
75 Writes will never block because the buffer never runs out of space;
76 old data is simply overwritten by new data.
77
78 jelson 1.1 You can read from the log in the normal way, e.g. using cat. Note
79 that reads block, just like "tail -f", waiting for new log data.
80 For example:
81
82 % cat /tmp/testlog
83 hello [we immediately see the hello that we wrote in the previous step]
84 _ [... and here's the cursor. the 'cat' process is now
85 blocked, waiting for new input. New data will be displayed
86 as it is written to the device by other processes.]
87 ^C [use control-c, for example, to stop reading.]
88
|
89 jelson 1.12 Note that the first process to consume data from an emlog buffer
90 will remove that text from the buffer. This differs from, say,
91 the behavior of the 'dmesg' buffer, which may be read many times
92 until it scrolls off.
|
93 jelson 1.1
94 4: Remove emlog when you're done
95
96 Type 'rmmod emlog' will remove the emlog kernel module and free all
|
97 jelson 1.3 associated buffers. This won't work until all emlog device files
98 are closed.
99
|
100 jelson 1.1
101
102 Other Usage Notes
103 =================
104
105 emlog will allocate a fixed-size buffer on behalf of a device file if
106 one of the following two conditions is true:
107
108 1- A process has the file open for reading or writing
109 2- A process has written text to the pipe that has not been read
110
111 In other words, buffers are persistent, even after a process closes
112 the pipe. If another process later reads the pipe, the text will
113 still be there. Note that it is possible (naturally) to fill virtual
114 memory by creating many such pipes, writing to all of them, and never
115 reading the data out of them. All buffers will be freed when the
116 emlog kernel module is removed.
117
|
118 jelson 1.12 Non-blocking reads work; i.e., setting O_NONBLOCK using ioctl() will
119 cause an EAGAIN to be returned if there is no data ready. In
120 addition, the select() and poll() functions will work correctly on
121 emlog devices.
122
123
124 Emlog and devfs
125 ===============
126
127 I love devfs and use it extensively, but I don't think it makes much
128 sense to use emlog with devfs. emlog lets you create as many log
129 devices as you like, anywhere on the filesystem -- the module tells
130 them apart based on their inode number. Having a single log device
131 always exist in a single place (/dev) is much less useful. So, I have
132 intentionally continued using the old register_chrdev interface
133 instead of using the new devfs_register_chrdev interface.
134
|
135 jelson 1.1
136 Troubleshooting
137 ===============
138
|
139 jelson 1.9 Q: When I try to compile emlog, I get hundreds of errors related
140 to header files.
141
|
142 jelson 1.12 A: If you've recently installed new kernel sources, make sure that
|
143 jelson 1.10 you've run "make config" or "make menuconfig" in /usr/src/linux. You
144 don't actually have to go through the entire configuration; just make
|
145 jelson 1.12 sure that you have a /usr/include/asm and a /usr/include/linux that
146 are symbolic links into your kernel source tree.
|
147 jelson 1.9
148
|
149 jelson 1.11 Q: When I try to insert the module using 'insmod', I get 'I/O error'.
|
150 jelson 1.1
151 A: That probably means the major device number being registered by
152 emlog is already in use by another device driver. Try changing the
153 major device number in emlog.h (or, change it to 0 in order to get a
154 dynamically assigned major number).
155
156
157 Q: I'm seeing "I/O error" at a time *other* then when the module is
158 inserted.
159
160 A: Oops - you've found a bug in emlog. Please report it.
161
162
163 Q: When I try to access an emlog device file for reading or writing,
164 I get the error "no such device".
165
|
166 jelson 1.12 A: This probably means either that the emlog kernel module is not
|
167 jelson 1.1 loaded; or, that the major number of the device file does not match
168 the major number that emlog registered. To see which major number is
169 being used by emlog, type 'cat /proc/devices | grep emlog'.
170
171
172 Q: When I try to access an emlog device file for reading or writing,
173 I get the error "invalid argument".
174
175 A: The *minor* number of the emlog device file must be a number
176 between 1 and 128, representing the number of kilobytes (1,024 bytes)
177 that should be used for emlog's ring buffer. Make sure you're
|
178 jelson 1.12 specifying a valid minor number in your 'mknod' statement. Don't use
179 0.
|
180 jelson 1.1
181
|
182 jelson 1.12 Q: I see "no memory" errors when I try opening new emlog files.
|
183 jelson 1.1
|
184 jelson 1.12 A: Looks like you're out of virtual memory, sport.
|
185 jelson 1.3
186
|
187 jelson 1.12 Q: When I try to remove the emlog driver ("rmmod emlog"), I get the
|
188 jelson 1.3 error "Device or resource busy".
189
|
190 jelson 1.12 A: That means a process is currently using an emlog device. You have
|
191 jelson 1.3 to wait until all processes close all emlog device files until the
192 driver can be removed. Try using "lsof" to see which files are in use
193 by which processes.
194
195
|
196 jelson 1.12 Q: When more than one process tries to read data from an emlog device,
197 only one gets it.
198
199 A: Yep, that's how it's supposed to work -- it differs from dmesg.
200 Unlike dmesg, emlog lets you block waiting for more input (like tail
201 -f). This was easier to implement by having buffers be consumed the
202 first time they were read.
203
|
204 jelson 1.3
|
205 jelson 1.12 Q: You've made my computer crash.
206
207 A: Sorry. If you can reproduce the problem I'll try to fix it.
|
208 jelson 1.1
209
210 Known Bugs
211 ==========
212
|
213 jelson 1.6 emlog identifies buffers based solely on the inode number of the
|
214 jelson 1.1 device file being accessed. If two device files on two different
|
215 jelson 1.3 filesystems happen to have the same inode number, they will share the
|
216 jelson 1.1 same buffer, as if they were the same device file.
217
|
218 jelson 1.3 Bug reports, patches, complaints, praise, and submissions of Central
219 Services Form 27B/6, are welcomed by the author (Jeremy Elson,
220 <jelson@circlemud.org>.
|
221 jelson 1.12
222
223 Version History
224 ===============
225
|
226 jelson 1.13 Version 0.30 (March 1, 2001)
|
227 jelson 1.12 - Now compiles correctly for 2.4 series kernels.
228 - select() and poll() now work correctly on emlog devices.
229 - Bug fix: all instances should not share one wait queue!
230
231 Version 0.20 (June 14, 2000)
232 - Initial public release.
|
233 jelson 1.1
234
235 Who wrote emlog, and why?
236 =========================
237
238 Emlog was written by Jeremy Elson <jelson@circlemud.org> at the
239 University of Southern California's Information Sciences Institute as
240 part of the SCADDS project <http://www.isi.edu/scadds>. SCADDS is an
241 embedded systems research project. We use small PC/104-bus-based
242 single-board-PCs using Linux. We wanted to save the debugging output
243 from certain processes, but since these things have 16MB of disk space
244 and 32MB of RAM, keeping complete log files was not an option. These
245 tiny nodes do have serial ports running PPP, though, so it's possible
246 to walk over to a node with a laptop, plug in a serial cable, and then
247 telnet into the box. Using emlog, we can always keep the most recent
248 debug messages from our processes; in case of an error, we can plug in
249 a debug console and see what went wrong.
250
|
251 jelson 1.3 This work was supported by DARPA under grant No. DABT63-99-1-0011 as
252 part of the SCADDS project, and was also made possible in part due to
253 support from Cisco Systems.
254
|
Return to
README
CVS log
Up to [CENS] / misc / emlog