[PATCH 4/4] relayfs: Documentation for exported relay fileops

[PATCH 4/4] relayfs: Documentation for exported relay fileops

[Tom Zanussi]

Documentation update for exported relay fileops support.

This patch depends on [PATCH 2/4] relayfs: Documentation 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
@@ -153,6 +153,8 @@ Here's a summary of the API relayfs prov
     subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
     buf_mapped(buf, filp)
     buf_unmapped(buf, filp)
+    create_buf_file(filename, parent, mode, buf, is_global)
+    remove_buf_file(dentry)
 
   helper functions:
 
@@ -347,6 +349,51 @@ for the file and an optional void * to a
 which will be accessible via inode->u.generic_ip (see the relay-apps
 tarball for examples).
 
+Creating relay files in other filesystems
+-----------------------------------------
+
+By default of course, relay_open() creates relay files in the relayfs
+filesystem.  Because relay_file_operations is exported, however, it's
+also possible to create and use relay files in other pseudo-filesytems
+such as debugfs.
+
+For this purpose, two callback functions are provided,
+create_buf_file() and remove_buf_file().  create_buf_file() is called
+once for each per-cpu buffer from relay_open() to allow the client to
+create a file to be used to represent the corresponding buffer; if
+this callback is not defined, the default implementation will create
+and return a file in the relayfs filesystem to represent the buffer.
+The callback should return the dentry of the file created to represent
+the relay buffer.  Note that the parent directory passed to
+relay_open() (and passed along to the callback), if specified, must
+exist in the same filesystem the new relay file is created in.  If
+create_buf_file() is defined, remove_buf_file() must also be defined;
+it's responsible for deleting the file(s) created in create_buf_file()
+and is called during relay_close().
+
+The create_buf_file() implementation can also be defined in such a way
+as to allow the creation of a single 'global' buffer instead of the
+default per-cpu set.  This can be useful for applications interested
+mainly in seeing the relative ordering of system-wide events without
+the need to bother with saving explicit timestamps for the purpose of
+merging/sorting per-cpu files in a postprocessing step.
+
+To have relay_open() create a global buffer, the create_buf_file()
+implementation should set the value of the is_global outparam to a
+non-zero value in addition to creating the file that will be used to
+represent the single buffer.  In the case of a global buffer,
+create_buf_file() and remove_buf_file() will be called only once.  The
+normal channel-writing functions e.g. relay_write() can still be used
+- writes from any cpu will transparently end up in the global buffer -
+but since it is a global buffer, callers should make sure they use the
+proper locking for such a buffer, either by wrapping writes in a
+spinlock, or by copying a write function from relayfs_fs.h and
+creating a local version that internally does the proper locking.
+
+See the 'exported-relayfile' examples in the relay-apps tarball for
+examples of creating and using both per-cpu and global relay files
+in debugfs.
+
 Misc
 ----
 

Re: [PATCH 4/4] relayfs: Documentation for exported relay fileops

[Andrew Morton]

Tom Zanussi <zanussi@us.ibm.com> wrote:
>
> +By default of course, relay_open() creates relay files in the relayfs
>  +filesystem.  Because relay_file_operations is exported, however, it's
>  +also possible to create and use relay files in other pseudo-filesytems
>  +such as debugfs.

Why would anyone wish to place relayfs files within other filesystems?

If users wish relayfs files to appear in other places, is it not sufficient
to do this with mount tricks?

Re: [PATCH 4/4] relayfs: Documentation for exported relay fileops

[Tom Zanussi]

Andrew Morton writes:
 > Tom Zanussi <zanussi@us.ibm.com> wrote:
 > >
 > > +By default of course, relay_open() creates relay files in the relayfs
 > >  +filesystem.  Because relay_file_operations is exported, however, it's
 > >  +also possible to create and use relay files in other pseudo-filesytems
 > >  +such as debugfs.
 > 
 > Why would anyone wish to place relayfs files within other
filesystems?

The reason they're exported is that when relayfs was being considered
for inclusion, GregKH requested that the relay file operations be
exported, which I did but didn't actually try to use them there until
now.  It turns out that the current patch's changes are needed in
order to be able to do that.  The reason behind being able to do this
I assume is so that developers can use relay files do ad hoc tracing
inside debugfs rather than have part of their application in debugfs
and another part in relayfs.  Maybe Greg can chime in as to whether he
thinks it's still useful, or maybe I should just remove the export?

Tom

Re: [PATCH 4/4] relayfs: Documentation for exported relay fileops

[Greg KH]

On Wed, Nov 09, 2005 at 04:37:13PM -0600, Tom Zanussi wrote:
> Andrew Morton writes:
>  > Tom Zanussi <zanussi@us.ibm.com> wrote:
>  > >
>  > > +By default of course, relay_open() creates relay files in the relayfs
>  > >  +filesystem.  Because relay_file_operations is exported, however, it's
>  > >  +also possible to create and use relay files in other pseudo-filesytems
>  > >  +such as debugfs.
>  > 
>  > Why would anyone wish to place relayfs files within other
> filesystems?
> 
> The reason they're exported is that when relayfs was being considered
> for inclusion, GregKH requested that the relay file operations be
> exported, which I did but didn't actually try to use them there until
> now.  It turns out that the current patch's changes are needed in
> order to be able to do that.  The reason behind being able to do this
> I assume is so that developers can use relay files do ad hoc tracing
> inside debugfs rather than have part of their application in debugfs
> and another part in relayfs.  Maybe Greg can chime in as to whether he
> thinks it's still useful

Yes, I still think that is very useful to have.  The relayfs core code
shouldn't rely on what filesystem is is placed into.

Thanks for doing this, I appreciate it.

greg k-h