[PATCH 2/4] relayfs: Documentation for non-relay file support

[PATCH 2/4] relayfs: Documentation for non-relay file support

[Tom Zanussi]

Documentation update for non-relay file support.

Signed-off-by: Tom Zanussi <zanussi@us.ibm.com>

---

diff --git a/Documentation/filesystems/relayfs.txt b/Documentation/filesystems/relayfs.txt
--- a/Documentation/filesystems/relayfs.txt
+++ b/Documentation/filesystems/relayfs.txt
@@ -44,30 +44,40 @@ relayfs can operate in a mode where it w
 collected by userspace, and not wait for it to consume it.
 
 relayfs itself does not provide for communication of such data between
-userspace and kernel, allowing the kernel side to remain simple and not
-impose a single interface on userspace. It does provide a separate
-helper though, described below.
+userspace and kernel, allowing the kernel side to remain simple and
+not impose a single interface on userspace. It does provide a set of
+examples and a separate helper though, described below.
+
+klog and relay-apps example code
+================================
+
+relayfs itself is ready to use, but to make things easier, a couple
+simple utility functions and a set of examples are provided.
+
+The relay-apps example tarball, available on the relayfs sourceforge
+site, contains a set of self-contained examples, each consisting of a
+pair of .c files containing boilerplate code for each of the user and
+kernel sides of a relayfs application; combined these two sets of
+boilerplate code provide glue to easily stream data to disk, without
+having to bother with mundane housekeeping chores.
+
+The 'klog debugging functions' patch (klog.patch in the relay-apps
+tarball) provides a couple of high-level logging functions to the
+kernel which allow writing formatted text or raw data to a channel,
+regardless of whether a channel to write into exists or not, or
+whether relayfs is compiled into the kernel or is configured as a
+module.  These functions allow you to put unconditional 'trace'
+statements anywhere in the kernel or kernel modules; only when there
+is a 'klog handler' registered will data actually be logged (see the
+klog and kleak examples for details).
+
+It is of course possible to use relayfs from scratch i.e. without
+using any of the relay-apps example code or klog, but you'll have to
+implement communication between userspace and kernel, allowing both to
+convey the state of buffers (full, empty, amount of padding).
 
-klog, relay-app & librelay
-==========================
-
-relayfs itself is ready to use, but to make things easier, two
-additional systems are provided.  klog is a simple wrapper to make
-writing formatted text or raw data to a channel simpler, regardless of
-whether a channel to write into exists or not, or whether relayfs is
-compiled into the kernel or is configured as a module.  relay-app is
-the kernel counterpart of userspace librelay.c, combined these two
-files provide glue to easily stream data to disk, without having to
-bother with housekeeping.  klog and relay-app can be used together,
-with klog providing high-level logging functions to the kernel and
-relay-app taking care of kernel-user control and disk-logging chores.
-
-It is possible to use relayfs without relay-app & librelay, but you'll
-have to implement communication between userspace and kernel, allowing
-both to convey the state of buffers (full, empty, amount of padding).
-
-klog, relay-app and librelay can be found in the relay-apps tarball on
-http://relayfs.sourceforge.net
+klog and the relay-apps examples can be found in the relay-apps
+tarball on http://relayfs.sourceforge.net
 
 The relayfs user space API
 ==========================
@@ -125,6 +135,8 @@ Here's a summary of the API relayfs prov
     relay_reset(chan)
     relayfs_create_dir(name, parent)
     relayfs_remove_dir(dentry)
+    relayfs_create_file(name, parent, mode, fops, data)
+    relayfs_remove_file(dentry)
 
   channel management typically called on instigation of userspace:
 
@@ -320,6 +332,21 @@ forces a sub-buffer switch on all the ch
 to finalize and process the last sub-buffers before the channel is
 closed.
 
+Creating non-relay files
+------------------------
+
+relay_open() automatically creates files in the relayfs filesystem to
+represent the per-cpu kernel buffers; it's often useful for
+applications to be able to create their own files in the relayfs
+filesystem as well e.g. 'control' files used to communicate control
+information between the kernel and user sides of a relayfs
+application.  For this purpose the relayfs_create_file() and
+relayfs_remove_file() API functions exist.  For relayfs_create_file(),
+the caller passes in a set of user-defined file operations to be used
+for the file and an optional void * to a user-specified data item,
+which will be accessible via inode->u.generic_ip (see the relay-apps
+tarball for examples).
+
 Misc
 ----
 

Re: [PATCH 2/4] relayfs: Documentation for non-relay file support

[Andrew Morton]

Tom Zanussi <zanussi@us.ibm.com> wrote:
>
>  +relay_open() automatically creates files in the relayfs filesystem to
>  +represent the per-cpu kernel buffers; it's often useful for
>  +applications to be able to create their own files in the relayfs
>  +filesystem as well e.g. 'control' files used to communicate control
>  +information between the kernel and user sides of a relayfs
>  +application.

What are the semantics of these control files?  How does an application
know that there's something new to be read from them?  select() or poll()
or blocking read()?

Can userspace write to the control files?   If so, what happens in-kernel?

Re: [PATCH 2/4] relayfs: Documentation for non-relay file support

[Tom Zanussi]

Andrew Morton writes:
 > Tom Zanussi <zanussi@us.ibm.com> wrote:
 > >
 > >  +relay_open() automatically creates files in the relayfs filesystem to
 > >  +represent the per-cpu kernel buffers; it's often useful for
 > >  +applications to be able to create their own files in the relayfs
 > >  +filesystem as well e.g. 'control' files used to communicate control
 > >  +information between the kernel and user sides of a relayfs
 > >  +application.
 > 
 > What are the semantics of these control files?  How does an application
 > know that there's something new to be read from them?  select() or poll()
 > or blocking read()?

It's completely up to the client to define whatever file operations it
wants, which are passed in to relayfs_create_file().  The relayfs
example apps, for instance, read from these files whenever they're
notifed via the relay file poll implementation that there's a
sub-buffer ready.  These are basically the same thing as proc or
debugfs files created by passing explicit file operations.

 > 
 > Can userspace write to the control files?   If so, what happens
in-kernel?

Yes, the client can supply a write() file op that does whatever it
wants to.  For the relayfs examples, the write() implementation
updates the count of sub-buffers consumed, for instance.

Tom