From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
linux-fsdevel@vger.kernel.org
Subject: [PATCH 35/44] docs: filesystems: convert relay.txt to ReST
Date: Mon, 17 Feb 2020 17:12:21 +0100 [thread overview]
Message-ID: <f48bb0fdf64d197f28c6f469adb61a7a091adb75.1581955849.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1581955849.git.mchehab+huawei@kernel.org>
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Use notes markups;
- Add it to filesystems/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/filesystems/index.rst | 1 +
.../filesystems/{relay.txt => relay.rst} | 129 +++++++++---------
2 files changed, 69 insertions(+), 61 deletions(-)
rename Documentation/filesystems/{relay.txt => relay.rst} (91%)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index b8689d082911..0aade8146d4d 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -84,5 +84,6 @@ Documentation for filesystem implementations.
proc
qnx6
ramfs-rootfs-initramfs
+ relay
virtiofs
vfat
diff --git a/Documentation/filesystems/relay.txt b/Documentation/filesystems/relay.rst
similarity index 91%
rename from Documentation/filesystems/relay.txt
rename to Documentation/filesystems/relay.rst
index cd709a94d054..04ad083cfe62 100644
--- a/Documentation/filesystems/relay.txt
+++ b/Documentation/filesystems/relay.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
relay interface (formerly relayfs)
==================================
@@ -108,6 +111,7 @@ The relay interface implements basic file operations for user space
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
@@ -136,13 +140,16 @@ poll() POLLIN/POLLRDNORM/POLLERR supported. User applications are
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.
@@ -154,7 +161,7 @@ The relay interface kernel API
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)
@@ -162,17 +169,17 @@ TBD(curr. line MT:/API/)
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)
@@ -180,7 +187,7 @@ TBD(curr. line MT:/API/)
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)
@@ -215,41 +222,41 @@ the file(s) created in create_buf_file() and is called during
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.
- */
-static struct dentry *create_buf_file_handler(const char *filename,
- struct dentry *parent,
- umode_t mode,
- struct rchan_buf *buf,
- int *is_global)
-{
- return debugfs_create_file(filename, mode, parent, buf,
- &relay_file_operations);
-}
+ /*
+ * create_buf_file() callback. Creates relay file in debugfs.
+ */
+ static struct dentry *create_buf_file_handler(const char *filename,
+ struct dentry *parent,
+ umode_t mode,
+ struct rchan_buf *buf,
+ int *is_global)
+ {
+ return debugfs_create_file(filename, mode, parent, buf,
+ &relay_file_operations);
+ }
-/*
- * remove_buf_file() callback. Removes relay file from debugfs.
- */
-static int remove_buf_file_handler(struct dentry *dentry)
-{
- debugfs_remove(dentry);
+ /*
+ * remove_buf_file() callback. Removes relay file from debugfs.
+ */
+ static int remove_buf_file_handler(struct dentry *dentry)
+ {
+ debugfs_remove(dentry);
- return 0;
-}
+ return 0;
+ }
-/*
- * relay interface callbacks
- */
-static struct rchan_callbacks relay_callbacks =
-{
- .create_buf_file = create_buf_file_handler,
- .remove_buf_file = remove_buf_file_handler,
-};
+ /*
+ * relay interface callbacks
+ */
+ static struct rchan_callbacks relay_callbacks =
+ {
+ .create_buf_file = create_buf_file_handler,
+ .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);
@@ -339,23 +346,23 @@ whether or not to actually move on to the next sub-buffer.
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,
- void *prev_subbuf,
- unsigned int prev_padding)
-{
- if (prev_subbuf)
- *((unsigned *)prev_subbuf) = prev_padding;
+ static int subbuf_start(struct rchan_buf *buf,
+ void *subbuf,
+ void *prev_subbuf,
+ unsigned int prev_padding)
+ {
+ if (prev_subbuf)
+ *((unsigned *)prev_subbuf) = prev_padding;
- if (relay_buf_full(buf))
- return 0;
+ if (relay_buf_full(buf))
+ return 0;
- subbuf_start_reserve(buf, sizeof(unsigned int));
+ subbuf_start_reserve(buf, sizeof(unsigned int));
- return 1;
-}
+ return 1;
+ }
If the current buffer is full, i.e. all sub-buffers remain unconsumed,
the callback returns 0 to indicate that the buffer switch should not
@@ -370,20 +377,20 @@ ready sub-buffers will relay_buf_full() return 0, in which case the
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,
- void *prev_subbuf,
- size_t prev_padding)
-{
- if (prev_subbuf)
- *((unsigned *)prev_subbuf) = prev_padding;
+ static int subbuf_start(struct rchan_buf *buf,
+ void *subbuf,
+ void *prev_subbuf,
+ size_t prev_padding)
+ {
+ if (prev_subbuf)
+ *((unsigned *)prev_subbuf) = prev_padding;
- subbuf_start_reserve(buf, sizeof(unsigned int));
+ subbuf_start_reserve(buf, sizeof(unsigned int));
- return 1;
-}
+ return 1;
+ }
In this case, the relay_buf_full() check is meaningless and the
callback always returns 1, causing the buffer switch to occur
--
2.24.1
next prev parent reply other threads:[~2020-02-17 16:12 UTC|newest]
Thread overview: 63+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <cover.1581955849.git.mchehab+huawei@kernel.org>
2020-02-17 16:11 ` [PATCH 01/44] docs: filesystems: convert 9p.txt to ReST Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 02/44] docs: filesystems: convert adfs.txt " Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 03/44] docs: filesystems: convert affs.txt " Mauro Carvalho Chehab
2020-02-18 13:04 ` David Sterba
2020-02-17 16:11 ` [PATCH 04/44] docs: filesystems: convert afs.txt " Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 05/44] docs: filesystems: convert autofs-mount-control.txt " Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 06/44] docs: filesystems: convert befs.txt " Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 07/44] docs: filesystems: convert bfs.txt " Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 08/44] docs: filesystems: convert btrfs.txt " Mauro Carvalho Chehab
2020-02-17 18:50 ` David Sterba
2020-02-17 19:34 ` Jonathan Corbet
2020-02-18 11:44 ` David Sterba
2020-02-17 16:11 ` [PATCH 09/44] docs: filesystems: convert ceph.txt " Mauro Carvalho Chehab
2020-02-18 11:57 ` Jeff Layton
2020-02-17 16:11 ` [PATCH 10/44] docs: filesystems: convert cramfs.txt " Mauro Carvalho Chehab
2020-02-17 18:11 ` Nicolas Pitre
2020-02-17 16:11 ` [PATCH 11/44] docs: filesystems: convert debugfs.txt " Mauro Carvalho Chehab
2020-02-17 16:11 ` [PATCH 12/44] docs: filesystems: convert dlmfs.txt " Mauro Carvalho Chehab
2020-02-18 1:21 ` Joseph Qi
2020-02-18 10:07 ` Mauro Carvalho Chehab
2020-02-18 10:55 ` Joseph Qi
2020-02-17 16:11 ` [PATCH 13/44] docs: filesystems: convert ecryptfs.txt " Mauro Carvalho Chehab
2020-02-17 20:07 ` Tyler Hicks
2020-02-17 16:12 ` [PATCH 14/44] docs: filesystems: convert efivarfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 15/44] docs: filesystems: convert erofs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 16/44] docs: filesystems: convert ext2.txt " Mauro Carvalho Chehab
2020-02-18 7:11 ` Jan Kara
2020-02-17 16:12 ` [PATCH 17/44] docs: filesystems: convert ext3.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 18/44] docs: filesystems: convert f2fs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 19/44] docs: filesystems: convert gfs2.txt " Mauro Carvalho Chehab
2020-02-18 13:13 ` Bob Peterson
2020-02-17 16:12 ` [PATCH 20/44] docs: filesystems: convert gfs2-uevents.txt " Mauro Carvalho Chehab
2020-02-18 13:13 ` Bob Peterson
2020-02-17 16:12 ` [PATCH 21/44] docs: filesystems: convert hfsplus.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 22/44] docs: filesystems: convert hfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 23/44] docs: filesystems: convert hpfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 24/44] docs: filesystems: convert inotify.txt " Mauro Carvalho Chehab
2020-02-18 7:10 ` Jan Kara
2020-02-17 16:12 ` [PATCH 25/44] docs: filesystems: convert isofs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 26/44] docs: filesystems: convert nilfs2.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 27/44] docs: filesystems: convert ntfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 28/44] docs: filesystems: convert ocfs2-online-filecheck.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 29/44] docs: filesystems: convert ocfs2.txt " Mauro Carvalho Chehab
2020-02-18 1:23 ` Joseph Qi
2020-02-17 16:12 ` [PATCH 30/44] docs: filesystems: convert omfs.txt " Mauro Carvalho Chehab
2020-02-18 0:57 ` Bob Copeland
2020-02-17 16:12 ` [PATCH 31/44] docs: filesystems: convert orangefs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 33/44] docs: filesystems: convert qnx6.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 34/44] docs: filesystems: convert ramfs-rootfs-initramfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` Mauro Carvalho Chehab [this message]
2020-02-17 16:12 ` [PATCH 36/44] docs: filesystems: convert romfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 37/44] docs: filesystems: convert squashfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 38/44] docs: filesystems: convert sysfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 39/44] docs: filesystems: convert sysv-fs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 40/44] docs: filesystems: convert tmpfs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 41/44] docs: filesystems: convert ubifs-authentication.rst.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 42/44] docs: filesystems: convert ubifs.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 43/44] docs: filesystems: convert udf.txt " Mauro Carvalho Chehab
2020-02-18 7:12 ` Jan Kara
2020-02-18 10:13 ` Mauro Carvalho Chehab
2020-02-18 10:57 ` Jan Kara
2020-02-17 16:12 ` [PATCH 44/44] docs: filesystems: convert zonefs.txt " Mauro Carvalho Chehab
2020-02-18 3:46 ` Damien Le Moal
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f48bb0fdf64d197f28c6f469adb61a7a091adb75.1581955849.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).