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 A: Make sure that you've run "make config" or "make menuconfig" in
119 /usr/src/linux. You don't actually have to go through the entire
120 configuration; just make sure that the symbolic link to your
121 architecture-specific header files is created.
122
123
|
124 jelson 1.1 Q: When I try insert the module using 'insmod', I get 'I/O error".
125
126 A: That probably means the major device number being registered by
127 emlog is already in use by another device driver. Try changing the
128 major device number in emlog.h (or, change it to 0 in order to get a
129 dynamically assigned major number).
130
131
132 Q: I'm seeing "I/O error" at a time *other* then when the module is
133 inserted.
134
135 A: Oops - you've found a bug in emlog. Please report it.
136
137
138 Q: When I try to access an emlog device file for reading or writing,
139 I get the error "no such device".
140
141 A: This probably means either that the emlog kernel module is not
142 loaded; or, that the major number of the device file does not match
143 the major number that emlog registered. To see which major number is
144 being used by emlog, type 'cat /proc/devices | grep emlog'.
145 jelson 1.1
146
147 Q: When I try to access an emlog device file for reading or writing,
148 I get the error "invalid argument".
149
150 A: The *minor* number of the emlog device file must be a number
151 between 1 and 128, representing the number of kilobytes (1,024 bytes)
152 that should be used for emlog's ring buffer. Make sure you're
153 specifying a valid minor number in your 'mknod' statement.
154
155
156 Q: I see "no memory" errors when I try opening new emlog files.
157
|
158 jelson 1.3 A: Looks like you're out of virtual memory, sport.
159
160
161 Q: When I try to remove the emlog driver ("rmmod emlog"), I get the
162 error "Device or resource busy".
163
164 A: That means a process is currently using an emlog device. You have
165 to wait until all processes close all emlog device files until the
166 driver can be removed. Try using "lsof" to see which files are in use
167 by which processes.
168
169
170 Q: You've made my computer crash.
171
172 A: Sorry. If you can reproduce the problem I'll try to fix it.
|
173 jelson 1.1
174
175 Known Bugs
176 ==========
177
|
178 jelson 1.6 emlog identifies buffers based solely on the inode number of the
|
179 jelson 1.1 device file being accessed. If two device files on two different
|
180 jelson 1.3 filesystems happen to have the same inode number, they will share the
|
181 jelson 1.1 same buffer, as if they were the same device file.
182
|
183 jelson 1.3 Currently, the poll() function for emlog files is unimplemented.
184 Therefore, using the select() function with an emlog file will not
185 work. (However, non-blocking reads DO work, e.g. by setting
186 O_NONBLOCK using ioctl()).
187
188 Bug reports, patches, complaints, praise, and submissions of Central
189 Services Form 27B/6, are welcomed by the author (Jeremy Elson,
190 <jelson@circlemud.org>.
|
191 jelson 1.1
192
193 Who wrote emlog, and why?
194 =========================
195
196 Emlog was written by Jeremy Elson <jelson@circlemud.org> at the
197 University of Southern California's Information Sciences Institute as
198 part of the SCADDS project <http://www.isi.edu/scadds>. SCADDS is an
199 embedded systems research project. We use small PC/104-bus-based
200 single-board-PCs using Linux. We wanted to save the debugging output
201 from certain processes, but since these things have 16MB of disk space
202 and 32MB of RAM, keeping complete log files was not an option. These
203 tiny nodes do have serial ports running PPP, though, so it's possible
204 to walk over to a node with a laptop, plug in a serial cable, and then
205 telnet into the box. Using emlog, we can always keep the most recent
206 debug messages from our processes; in case of an error, we can plug in
207 a debug console and see what went wrong.
208
|
209 jelson 1.3 This work was supported by DARPA under grant No. DABT63-99-1-0011 as
210 part of the SCADDS project, and was also made possible in part due to
211 support from Cisco Systems.
212
|
Return to
README
CVS log
Up to [CENS] / misc / emlog