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