Skip to contentSkip to conversation

relayfs redux, part 5

PATCH In review Tom Zanussi 2 participants 2 messages Feb 18, 2005 – Feb 21, 2005

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 relayfs redux, part 5

Hi,

Here's the latest version of relayfs, with changes incorporating the previous round of suggestions. Thanks to Pekka Enberg and Maneesh Soni for commenting on the previous patch. Since there weren't any complaints about the API last time, I went ahead and did some SMP testing (see below) and wrote some Documentation. The patch size without the documentation hasn't changed much and is still about 41K.

Here's a list of the changes in this version:

- cleaned up some of the code in buffers.c and moved everything buffer-related there.
- got rid of the extra parameter in relay_create_entry().
- added a prev_subbuf_data param to the subbuf_start() callback.
- the subbuf_start() callback is now called for the first sub-buffer when a buffer is created.
- added relay_flush(), needed when closing a channel.
- added sanity checks to all the non-performance-critical API functions.
- some small changes needed for proper handling of the buffer-full condition.
- the reserved address is now passed into relay_commit() in order to make it easier to use.
- added kref to channel
- other random cleanup

I've done some pretty heavy pounding on this version and haven't had much luck breaking it yet. ;-) Using a hacked version of the kprobes network packet tracing module, I tested it on a couple different
systems: a 4x700MHz Pentium III SMP system and a 3GHz Pentium 4 system with hyperthreading on.

Here's a summary of the results of the test on the 4x700MHz Pentium III system:

The following tests were run while transferring a 1 Gb test file. All numbers are averaged over 5 runs.

1) 5:37.58 minutes - baseline, netpktlog not inserted
2) 5:46.76 minutes - netpktlog inserted, but with empty kprobes handlers
3) 6:26.29 minutes - formatting data but no relay_write
4) 6:27.71 minutes - relay_write() with logging to disk
5) 6:27.70 minutes - relay_write() with no logging to disk

The average trace file size generated for 4), which is the only test that generates data, was 1,154,171,258 bytes (yes, the trace file is larger than the transferred file).

The total event count for 4) was 6,770,949 events of average length 149.

The amount of data logged in this test averaged 2.98 Mb/sec, and the average number of events logged was 17464/sec.

Some comments:

For 2), I hadn't intended on testing the efficiency of kprobes, but since I was there I thought I'd try replacing the handler code with nothing but jprobes_return() and see what kind of overhead kprobes alone introduces. On this system, there was a small but noticeable hit due to kprobes. On the 3 GHz P4 system, this didn't show up in the numbers.

For 3) nothing is being written to the relayfs channel - the main thing going on in the kprobes handlers is the formatting of the data using vsnprintf(), which here seems very expensive. On the other system tested, it was much less of a factor in the numbers.

For 4) and 5), writing to the channel using relay_write() seems to be pretty efficient; in any case the numbers don't show a significant hit to this system even when logging to disk. Of course, the fact that the numbers with and without logging to disk were essentially the same means that the disk subsystem is pretty efficient too. Since this wasn't a very controlled test, I don't really trust any numbers this close together, but using them anyway, it shows about a 0.3 - 0.4% overhead when logging 3Mb/sec to disk on this system. Actually, there was one run that was 3 seconds longer than the others - if we remove that the average time was 6:27.03 minutes, which makes it < 0.2%.

Here's a summary of the results of the test on the 3GHz hyperthreading system:

The following tests were run while transferring a 250Mb test file. All numbers are averaged over 3 runs.

1) 4:38.79 minutes - baseline, netpktlog not inserted
2) 4:37.73 minutes - formatting data but no relay_write
3) 4:43.70 minutes - relay_write() with logging to disk
4) 4:37.59 minutes - relay_write() with no logging to disk

The average trace file size generated for 3), which is the only test that generates data, was 295,514,458 bytes.

The total event count for 3) was 1,683,751 events of average length 176.

The amount of data logged in this test averaged 913 Kb/sec, and the average number of events logged was 5202/sec.

Some comments:

For 2) the kprobes cost and the cost of formatting the data doesn't show up in the numbers at all, maybe since it's a much faster processor.

For 3) the number basically reflects the cost of logging the trace data to disk for this system and not the cost of relay_write(), since as we can see from 4), if not logging to disk there's essentially no difference between the relay_write() and no-relay_write() runs. Again, this wasn't a controlled test, so any differences here are definitely in the noise.

The network packet tracing module and userspace program I used for testing can be found here (the raw test data is also included):

http://prdownloads.sourceforge.net/dprobes/plog.tar.gz?download

Thanks,

Tom

 Documentation/filesystems/relayfs.txt |  200 ++++++++++++
 fs/Kconfig                            |   12 
 fs/Makefile                           |    1 
 fs/relayfs/Makefile                   |    4 
 fs/relayfs/buffers.c                  |  204 ++++++++++++
 fs/relayfs/buffers.h                  |   12 
 fs/relayfs/inode.c                    |  426 ++++++++++++++++++++++++++
 fs/relayfs/relay.c                    |  552 ++++++++++++++++++++++++++++++++++
 fs/relayfs/relay.h                    |   27 +
 include/linux/relayfs_fs.h            |  269 ++++++++++++++++
 10 files changed, 1707 insertions(+)
Documentation/filesystems/relayfs.txt +200 -0
diff -urpN -X dontdiff linux-2.6.10/Documentation/filesystems/relayfs.txt linux-2.6.10-cur/Documentation/filesystems/relayfs.txt
@@ -0,0 +1,200 @@
+
+relayfs - a high-speed data relay filesystem
+============================================
+
+relayfs is a filesystem designed to provide an efficient mechanism for
+tools and facilities to relay large and potentially sustained streams
+of data from kernel space to user space.
+
+The main abstraction of relayfs is the 'channel'.  A channel consists
+of a set of per-cpu kernel buffers each represented by a file in the
+relayfs filesystem.  Kernel clients write into a channel using
+efficient write functions which automatically log to the current cpu's
+channel buffer.  User space applications mmap() the per-cpu files and
+retrieve the data as it becomes available.
+
+The format of the data logged into the channel buffers is completely
+up to the relayfs client; relayfs does however provide hooks which
+allow clients to impose some stucture on the buffer data.  Nor does
+relayfs implement any form of data filtering - this also is left to
+the client.  The purpose is to keep relayfs as simple as possible.
+
+This document provides an overview of the relayfs API.  The details of
+the function parameters are documented along with the functions in the
+filesystem code - please see that for details.
+
+
+The relayfs user space API
+==========================
+
+relayfs implements basic file operations for user space access to
+relayfs channel buffer data.  Here are the file operations that are
+available and some comments regarding their behavior:
+
+open()	 enables user to open an _existing_ buffer.
+
+mmap()	 results in channel buffer being mapped into the caller's
+	 memory space.
+
+poll()	 POLLIN/POLLRDNORM/POLLERR supported.  User applications are
+	 notified when sub-buffer boundaries are crossed.
+
+close() decrements the channel buffer's refcount.  When the refcount
+	reaches 0 i.e. when no process or kernel client has the buffer
+	open, the channel buffer is freed.
+
+
+In order for a user application to make use of relayfs files, the
+relayfs filesystem must be mounted.  For example,
+
+	mount -t relayfs relayfs /mnt/relay
+
+NOTE:	relayfs doesn't need to be mounted for kernel clients to create
+	or use channels - it only needs to be mounted when user space
+	applications need access to the buffer data.
+
+
+The relayfs kernel API
+======================
+
+Here's a summary of the API relayfs provides to in-kernel clients:
+
+
+  channel management functions:
+
+    relay_open(base_filename, parent, subbuf_size, n_subbufs,
+               attribute_flags, callbacks)
+    relay_close(chan)
+    relay_flush(chan)
+    relay_reset(chan)
+    relayfs_create_dir(name, parent)
+    relayfs_remove_dir(dentry)
+    relay_commit(buf, reserved, count)
+    relay_subbufs_consumed(chan, cpu, subbufs_consumed)
+
+  write functions:
+
+    relay_write(chan, data, length)
+    __relay_write(chan, data, length)
+    relay_reserve(chan, length)
+
+  callbacks:
+
+    subbuf_start(buf, subbuf, prev_subbuf_idx, prev_subbuf)
+    deliver(buf, subbuf_idx, subbuf)
+    buf_mapped(buf, filp)
+    buf_unmapped(buf, filp)
+    buf_full(buf, subbuf_idx)
+
+
+A relayfs channel is made of up one or more per-cpu channel buffers,
+each implemented as a circular buffer subdivided into one or more
+sub-buffers.
+
+relay_open() is used to create a channel, along with its per-cpu
+channel buffers.  Each channel buffer will have an associated file
+created for it in the relayfs filesystem, which can be opened and
+mmapped from user space if desired.  The files are named
+basename0...basenameN-1 where N is the number of online cpus, and by
+default will be created in the root of the filesystem.  If you want a
+directory structure to contain your relayfs files, you can create it
+with relayfs_create_dir() and pass the parent directory to
+relay_open().  Clients are responsible for cleaning up any directory
+structure they create when the channel is closed - use
+relayfs_remove_dir() for that.
+
+The total size of each per-cpu buffer is calculated by multiplying the
+number of sub-buffers by the sub-buffer size passed into relay_open().
+The idea behind sub-buffers is that they're basically an extension of
+double-buffering to N buffers, and they also allow applications to
+easily implement random-access-on-buffer-boundary schemes, which can
+be important for some high-volume applications.  The number and size
+of sub-buffers is completely dependent on the application and even for
+the same application, different conditions will warrant different
+values for these parameters at different times.  Typically, the right
+values to use are best decided after some experimentation; in general,
+though, it's safe to assume that having only 1 sub-buffer is a bad
+idea - you're guaranteed to either overwrite data or lose events
+depending on the channel mode being used.
+
+relayfs channels can be opened in either of two modes - 'continuous'
+or 'no-overwrite'.  In continuous mode, writes continuously cycle
+around the buffer and will never fail, but will unconditionally
+overwrite old data regardless of whether it's actually been consumed.
+In no-overwrite mode, writes will fail i.e. data will be lost, if the
+number of unconsumed sub-buffers equals the total number of
+sub-buffers in the channel.  In this mode, the client is reponsible
+for notifying relayfs when sub-buffers have been consumed via
+relay_subbufs_consumed().  A full buffer will become 'unfull' and
+logging will continue once the client calls relay_subbufs_consumed()
+again.  When a buffer becomes full, the buf_full() callback is invoked
+to notify the client.  In both modes, the subbuf_start() callback will
+notify the client whenever a sub-buffer boundary is crossed.  This can
+be used to write header information into the new sub-buffer or fill in
+header information reserved in the previous sub-buffer. subbuf_start()
+is also called for the first sub-buffer in each channel buffer when
+the channel is created.  The mode is specified to relay_open() using
+the RELAY_MODE_NO_OVERWRITE and RELAY_MODE_CONTINUOUS flags.
+
+kernel clients write data into the current cpu's channel buffer using
+relay_write() or __relay_write().  relay_write() is the main logging
+function - it uses local_irqsave() to protect the buffer and should be
+used if you might be logging from interrupt context.  If you know
+you'll never be logging from interrupt context, you can use
+__relay_write(), which only disables preemption.  These functions
+don't return a value, so you can't determine whether or not they
+failed - the assumption is that you wouldn't want to check a return
+value in the fast logging path anyway, and that they'll always succeed
+unless the buffer is full and in no-overwrite mode, in which case
+you'll be notified via the buf_full() callback.
+
+relay_reserve() is used to reserve a slot in a channel buffer which
+can be written to later.  This would typically be used in applications
+that need to write directly into a channel buffer without having to
+stage data in a temporary buffer beforehand.  Because the actual write
+may not happen immediately after the slot is reserved, applications
+using relay_reserve() can call relay_commit() to notify relayfs when
+the slot has actually been written.  When all the reserved slots have
+been committed, the deliver() callback is invoked to notify the client
+that a guaranteed full sub-buffer has been produced.  Because the
+write is under control of the client and is separated from the
+reserve, relay_reserve() doesn't protect the buffer at all - it's up
+to the client to provide the appropriate synchronization when using
+relay_reserve().
+
+The client calls relay_close() when it's finished using the channel.
+The channel and its associated buffers are destroyed when there are no
+longer any references to any of the channel buffers.  relay_flush()
+forces a sub-buffer switch on all the channel buffers, and can be used
+to finalize and process the last sub-buffers before the channel is
+closed.
+
+Some applications may want to keep a channel around and re-use it
+rather than open and close a new channel for each use.  relay_reset()
+can be used for this purpose - it resets a channel to its initial
+state without reallocating channel buffer memory or destroying
+existing mappings.  It should however only be called when it's safe to
+do so i.e. when the channel isn't currently being written to.
+
+Finally, there are a couple of utility callbacks that can be used for
+different purposes.  buf_mapped() is called whenever a channel buffer
+is mmapped from user space and buf_unmapped() is called when it's
+unmapped.  The client can use this notification to trigger actions
+within the kernel application, such as enabling/disabling logging to
+the channel.
+
+
+Credits
+=======
+
+The ideas and specs for relayfs came about as a result of discussions
+on tracing involving the following:
+
+Michel Dagenais		<[email protected]>
+Richard Moore		<[email protected]>
+Bob Wisniewski		<[email protected]>
+Karim Yaghmour		<[email protected]>
+Tom Zanussi		<[email protected]>
+
+Also thanks to Hubertus Franke for a lot of useful suggestions and bug
+reports.
fs/Kconfig +12 -0
diff -urpN -X dontdiff linux-2.6.10/fs/Kconfig linux-2.6.10-cur/fs/Kconfig
@@ -972,6 +972,18 @@ config RAMFS
 	  To compile this as a module, choose M here: the module will be called
 	  ramfs.
 
+config RELAYFS_FS
+	tristate "Relayfs file system support"
+	---help---
+	  Relayfs is a high-speed data relay filesystem designed to provide
+	  an efficient mechanism for tools and facilities to relay large
+	  amounts of data from kernel space to user space.
+
+	  To compile this code as a module, choose M here: the module will be
+	  called relayfs.
+
+	  If unsure, say N.
+
 endmenu
 
 menu "Miscellaneous filesystems"
fs/Makefile +1 -0
diff -urpN -X dontdiff linux-2.6.10/fs/Makefile linux-2.6.10-cur/fs/Makefile
@@ -94,3 +94,4 @@ obj-$(CONFIG_AFS_FS)		+= afs/
 obj-$(CONFIG_BEFS_FS)		+= befs/
 obj-$(CONFIG_HOSTFS)		+= hostfs/
 obj-$(CONFIG_HPPFS)		+= hppfs/
+obj-$(CONFIG_RELAYFS_FS)	+= relayfs/
fs/relayfs/Makefile +4 -0
diff -urpN -X dontdiff linux-2.6.10/fs/relayfs/Makefile linux-2.6.10-cur/fs/relayfs/Makefile
@@ -0,0 +1,4 @@
+obj-$(CONFIG_RELAYFS_FS) += relayfs.o
+
+relayfs-y := relay.o inode.o buffers.o
+
fs/relayfs/buffers.c +204 -0

204 lines not on this page · raw message

fs/relayfs/buffers.h +12 -0
diff -urpN -X dontdiff linux-2.6.10/fs/relayfs/buffers.h linux-2.6.10-cur/fs/relayfs/buffers.h
@@ -0,0 +1,12 @@
+#ifndef _BUFFERS_H
+#define _BUFFERS_H
+
+/* This inspired by rtai/shmem */
+#define FIX_SIZE(x) (((x) - 1) & PAGE_MASK) + PAGE_SIZE
+
+extern int relay_mmap_buf(struct rchan_buf *buf, struct vm_area_struct *vma);
+extern struct rchan_buf *relay_create_buf(struct rchan *chan);
+extern void relay_destroy_buf(struct rchan_buf *buf);
+extern void relay_remove_buf(struct kref *kref);
+
+#endif/* _BUFFERS_H */
fs/relayfs/inode.c +426 -0

426 lines not on this page · raw message

fs/relayfs/relay.c +552 -0

552 lines not on this page · raw message

fs/relayfs/relay.h +27 -0
diff -urpN -X dontdiff linux-2.6.10/fs/relayfs/relay.h linux-2.6.10-cur/fs/relayfs/relay.h
@@ -0,0 +1,27 @@
+/*
+ * fs/relayfs/relay.h
+ *
+ * Copyright (C) 1999-2005 - Karim Yaghmour ([email protected]), Opersys inc.
+ * Copyright (C) 2002, 2003 - Tom Zanussi ([email protected]), IBM Corp
+ *
+ * RelayFS internal definitions and declarations
+ */
+
+#ifndef _RELAY_H
+#define _RELAY_H
+
+/*
+ * Internal relayfs kernel API, fs/relayfs/relay.c
+ */
+
+#define relay_mode_continuous(chan) (((chan)->flags & RELAY_MODE_CONTINUOUS) ? 1 : 0)
+
+struct dentry *relayfs_create_file(const char *name,
+				   struct dentry *parent,
+				   int mode,
+				   struct rchan *chan);
+extern int relayfs_remove(struct dentry *dentry);
+extern int relay_buf_empty(struct rchan_buf *buf);
+extern void relay_destroy_channel(struct kref *kref);
+
+#endif /* _RELAY_H */
include/linux/relayfs_fs.h +269 -0

269 lines not on this page · raw message

#1 lore raw

Hi Tom,

More nitpick follows.

Quoted 32 lines

diff -urpN -X dontdiff linux-2.6.10/fs/Makefile linux-2.6.10-cur/fs/Makefile

fs/Makefile +29 -0
+/**
+ *	relay_create_buf - allocate and initialize a channel buffer
+ *	@alloc_size: size of the buffer to allocate
+ *	@n_subbufs: number of sub-buffers in the channel
+ *
+ *	Returns channel buffer if successful, NULL otherwise
+ */
+struct rchan_buf *relay_create_buf(struct rchan *chan)
+{
+	struct rchan_buf *buf = kcalloc(1, sizeof(struct rchan_buf), GFP_KERNEL);
+	if (!buf)
+		return NULL;
+
+	buf->padding = kmalloc(chan->n_subbufs * sizeof(unsigned *), GFP_KERNEL);
+	if (!buf->padding)
+		goto free_buf;
+	
+	buf->commit = kmalloc(chan->n_subbufs * sizeof(unsigned *), GFP_KERNEL);
+	if (!buf->commit)
+		goto free_padding;
+
+	buf->start = relay_alloc_buf(chan->alloc_size, &buf->page_array, &buf->page_count);
+	if (!buf->start)
+		goto free_commit;
+
+	buf->chan = chan;
+	kref_get(&buf->chan->kref);
+	return buf;
+

fs/Makefile

Quoted 10 lines
fs/Makefile +10 -0
+free_commit:
+	kfree(buf->commit);
+
+free_padding:
+	kfree(buf->padding);
+
+free_buf:
+	kfree(buf);
+	return NULL;
+}

kfree() deals with NULL pointers and since we're zeroing all of them when we call kcalloc(), you only need one failure goto where you unconditionally execute all kfree() calls.

Quoted 13 lines

diff -urpN -X dontdiff linux-2.6.10/fs/relayfs/inode.c linux-2.6.10-cur/fs/relayfs/inode.c

fs/relayfs/inode.c +9 -0
@@ -0,0 +1,426 @@
+/**
+ *	relayfs_create_file - create a file in the relay filesystem
+ *	@name: the name of the file to create
+ *	@parent: parent directory
+ *	@mode: mode, if not specied the default perms are used
+ *	@chan: channel associated with the file
+ *
+ *	Returns file dentry if successful, NULL otherwise.
+ *

fs/relayfs/inode.c line 19

Quoted 10 lines
fs/relayfs/inode.c +10 -0
+ *	The file will be created user r on behalf of current user.
+ */
+struct dentry *relayfs_create_file(const char *name, struct dentry *parent,
+				   int mode, struct rchan *chan)
+{
+	if (!mode)
+		mode = S_IRUSR;
+	mode = (mode & S_IALLUGO) | S_IFREG;
+
+	return relayfs_create_entry(name, parent, mode, chan);

Shouldn't we check if name is NULL here like in relayfs_create_dir? Perhaps the check should be moved to relayfs_create_entry().

include/linux/relayfs_fs.h line 6

Quoted 10 lines

diff -urpN -X dontdiff linux-2.6.10/include/linux/relayfs_fs.h linux-2.6.10-cur/include/linux/relayfs_fs.h

include/linux/relayfs_fs.h +6 -0
@@ -0,0 +1,269 @@
+
+/*
+ * Relay attribute flags
+ */
+#define RELAY_MODE_CONTINUOUS		0x1
+#define RELAY_MODE_NO_OVERWRITE		0x2

These are mutually exclusive so they're really a boolean that states
whether overwrite is allowed or not. Therefore please either make struct
rchan flags a boolean (it is only used for this) or turn the above to a single bit flag (cleared for not allowed, set for allowed) and then drop check_attribute_flags().

Pekka