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