docs: filesystems: convert relay.txt to ReST

   proc

   qnx6

   ramfs-rootfs-initramfs

   relay

   virtiofs

   vfat

.. SPDX-License-Identifier: GPL-2.0

==================================

relay interface (formerly relayfs)

==================================

access to relay channel buffer data.  Here are the file operations

that are available and some comments regarding their behavior:

=========== ============================================================

open()	    enables user to open an _existing_ channel buffer.

mmap()      results in channel buffer being mapped into the caller's

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 relay files, the

host filesystem must be mounted.  For example,

host filesystem must be mounted.  For example::

	mount -t debugfs debugfs /sys/kernel/debug

NOTE:   the host filesystem doesn't need to be mounted for kernel

.. Note::

	the host filesystem 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.

Here's a summary of the API the relay interface provides to in-kernel clients:

TBD(curr. line MT:/API/)

  channel management functions:

  channel management functions::

    relay_open(base_filename, parent, subbuf_size, n_subbufs,

               callbacks, private_data)

    relay_flush(chan)

    relay_reset(chan)

  channel management typically called on instigation of userspace:

  channel management typically called on instigation of userspace::

    relay_subbufs_consumed(chan, cpu, subbufs_consumed)

  write functions:

  write functions::

    relay_write(chan, data, length)

    __relay_write(chan, data, length)

    relay_reserve(chan, length)

  callbacks:

  callbacks::

    subbuf_start(buf, subbuf, prev_subbuf, prev_padding)

    buf_mapped(buf, filp)

    create_buf_file(filename, parent, mode, buf, is_global)

    remove_buf_file(dentry)

  helper functions:

  helper functions::

    relay_buf_full(buf)

    subbuf_start_reserve(buf, length)

relay_close().

Here are some typical definitions for these callbacks, in this case

using debugfs:

using debugfs::

    /*

    * create_buf_file() callback.  Creates relay file in debugfs.

	    .remove_buf_file = remove_buf_file_handler,

    };

And an example relay_open() invocation using them:

And an example relay_open() invocation using them::

  chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);

To implement 'no-overwrite' mode, the userspace client would provide

an implementation of the subbuf_start() callback something like the

following:

following::

    static int subbuf_start(struct rchan_buf *buf,

			    void *subbuf,

buffer switch can continue.

The implementation of the subbuf_start() callback for 'overwrite' mode

would be very similar:

would be very similar::

    static int subbuf_start(struct rchan_buf *buf,

			    void *subbuf,