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