Skip to contentSkip to conversation

Documentation: nfs: convert remaining files to ReST.

PATCH Applied Daniel W. S. Almeida 2 participants 7 messages Jan 29, 2020 – Feb 13, 2020

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

v2 cover Documentation: nfs: convert remaining files to ReST.

From: "Daniel W. S. Almeida" <[email protected]>

This series completes the conversion of Documentation/filesystems/nfs to ReST.

I did not think these rst files were supposed to be in admin-guide, so I left them where they are.

Changes in v2:
Change csv-table to ReST grid table format Remove "#." syntax

Daniel W. S. Almeida (5):
Documentation: nfs: convert pnfs.txt to ReST
Documentation: nfs: rpc-cache: convert to ReST
Documentation: nfs: rpc-server-gss: convert to ReST
Documentation: nfs: nfs41-server: convert to ReST
Documentation: nfs: knfsd-stats: convert to ReST

 Documentation/filesystems/index.rst           |   1 +
 Documentation/filesystems/nfs/index.rst       |  13 +
 .../nfs/{knfsd-stats.txt => knfsd-stats.rst}  |  17 +-
 .../filesystems/nfs/nfs41-server.rst          | 256 ++++++++++++++++++
 .../filesystems/nfs/nfs41-server.txt          | 173 ------------
 .../filesystems/nfs/{pnfs.txt => pnfs.rst}    |  25 +-
 .../nfs/{rpc-cache.txt => rpc-cache.rst}      | 136 ++++++----
 ...{rpc-server-gss.txt => rpc-server-gss.rst} |  19 +-
 8 files changed, 381 insertions(+), 259 deletions(-)
 create mode 100644 Documentation/filesystems/nfs/index.rst
 rename Documentation/filesystems/nfs/{knfsd-stats.txt => knfsd-stats.rst} (95%)
 create mode 100644 Documentation/filesystems/nfs/nfs41-server.rst
 delete mode 100644 Documentation/filesystems/nfs/nfs41-server.txt
 rename Documentation/filesystems/nfs/{pnfs.txt => pnfs.rst} (87%)
 rename Documentation/filesystems/nfs/{rpc-cache.txt => rpc-cache.rst} (66%)
 rename Documentation/filesystems/nfs/{rpc-server-gss.txt => rpc-server-gss.rst} (92%)
Signature · 1 line
2.25.0
#1 lore raw

PATCH v2 1/5 Documentation: nfs: convert pnfs.txt to ReST

From: "Daniel W. S. Almeida" <[email protected]>

Convert pnfs.txt to ReST. Content remains mostly unchanged.

---
 Documentation/filesystems/index.rst           |  1 +
 Documentation/filesystems/nfs/index.rst       |  9 +++++++
 .../filesystems/nfs/{pnfs.txt => pnfs.rst}    | 25 +++++++++++--------
 3 files changed, 25 insertions(+), 10 deletions(-)
 create mode 100644 Documentation/filesystems/nfs/index.rst
 rename Documentation/filesystems/nfs/{pnfs.txt => pnfs.rst} (87%)
Documentation/filesystems/index.rst +1 -0
index ad6315a48d14..801d773a44b9 100644
@@ -48,3 +48,4 @@ Documentation for filesystem implementations.
 
    autofs
    virtiofs
+   nfs/index
Documentation/filesystems/nfs/index.rst new file +9 -0
new file mode 100644
index 000000000000..d19ba592779a
@@ -0,0 +1,9 @@
+===============================
+NFS
+===============================
+
+
+.. toctree::
+   :maxdepth: 1
+
+   pnfs
Documentation/filesystems/nfs/pnfs.rst renamed from Documentation/filesystems/nfs/pnfs.txt +15 -10
similarity index 87%
rename from Documentation/filesystems/nfs/pnfs.txt
rename to Documentation/filesystems/nfs/pnfs.rst
index 80dc0bdc302a..7c470ecdc3a9 100644
@@ -1,15 +1,17 @@
-Reference counting in pnfs:
+==========================
+Reference counting in pnfs
 ==========================
 
 The are several inter-related caches.  We have layouts which can
 reference multiple devices, each of which can reference multiple data servers.
 Each data server can be referenced by multiple devices.  Each device
-can be referenced by multiple layouts.  To keep all of this straight,
+can be referenced by multiple layouts. To keep all of this straight,
 we need to reference count.
 
 
 struct pnfs_layout_hdr
-----------------------
+======================
+
 The on-the-wire command LAYOUTGET corresponds to struct
 pnfs_layout_segment, usually referred to by the variable name lseg.
 Each nfs_inode may hold a pointer to a cache of these layout
@@ -25,7 +27,8 @@ the reference count, as the layout is kept around by the lseg that
 keeps it in the list.
 
 deviceid_cache
---------------
+==============
+
 lsegs reference device ids, which are resolved per nfs_client and
 layout driver type.  The device ids are held in a RCU cache (struct
 nfs4_deviceid_cache).  The cache itself is referenced across each
@@ -38,24 +41,26 @@ justification, but seems reasonable given that we can have multiple
 deviceid's per filesystem, and multiple filesystems per nfs_client.
 
 The hash code is copied from the nfsd code base.  A discussion of
-hashing and variations of this algorithm can be found at:
-http://groups.google.com/group/comp.lang.c/browse_thread/thread/9522965e2b8d3809
+hashing and variations of this algorithm can be found `here.
+<http://groups.google.com/group/comp.lang.c/browse_thread/thread/9522965e2b8d3809>`_
 
 data server cache
------------------
+=================
+
 file driver devices refer to data servers, which are kept in a module
 level cache.  Its reference is held over the lifetime of the deviceid
 pointing to it.
 
 lseg
-----
+====
+
 lseg maintains an extra reference corresponding to the NFS_LSEG_VALID
 bit which holds it in the pnfs_layout_hdr's list.  When the final lseg
 is removed from the pnfs_layout_hdr's list, the NFS_LAYOUT_DESTROYED
 bit is set, preventing any new lsegs from being added.
 
 layout drivers
---------------
+==============
 
 PNFS utilizes what is called layout drivers. The STD defines 4 basic
 layout types: "files", "objects", "blocks", and "flexfiles". For each
@@ -68,6 +73,6 @@ Blocks-layout-driver code is in: fs/nfs/blocklayout/.. directory
 Flexfiles-layout-driver code is in: fs/nfs/flexfilelayout/.. directory
 
 blocks-layout setup
--------------------
+===================
 
 TODO: Document the setup needs of the blocks layout driver
Signature · 1 line
2.25.0
#2 lore raw

PATCH v2 2/5 Documentation: nfs: rpc-cache: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert rpc-cache.txt to ReST. Changes aim to improve presentation but the content itself remains mostly the same.

---
 Documentation/filesystems/nfs/index.rst       |   1 +
 .../nfs/{rpc-cache.txt => rpc-cache.rst}      | 136 ++++++++++--------
 2 files changed, 78 insertions(+), 59 deletions(-)
 rename Documentation/filesystems/nfs/{rpc-cache.txt => rpc-cache.rst} (66%)
Documentation/filesystems/nfs/index.rst +1 -0
index d19ba592779a..52f4956e7770 100644
@@ -7,3 +7,4 @@ NFS
    :maxdepth: 1
 
    pnfs
+   rpc-cache
Documentation/filesystems/nfs/rpc-cache.rst renamed from Documentation/filesystems/nfs/rpc-cache.txt +77 -59

203 lines not on this page · raw message

Signature · 1 line
2.25.0
#3 lore raw

PATCH v2 3/5 Documentation: nfs: rpc-server-gss: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert rpc-server-gss.txt to ReST. Content remains mostly unchanged.

---
 Documentation/filesystems/nfs/index.rst       |  1 +
 ...{rpc-server-gss.txt => rpc-server-gss.rst} | 19 +++++++++++--------
 2 files changed, 12 insertions(+), 8 deletions(-)
 rename Documentation/filesystems/nfs/{rpc-server-gss.txt => rpc-server-gss.rst} (92%)
Documentation/filesystems/nfs/index.rst +1 -0
index 52f4956e7770..9d5365cbe2c3 100644
@@ -8,3 +8,4 @@ NFS
 
    pnfs
    rpc-cache
+   rpc-server-gss
Documentation/filesystems/nfs/rpc-server-gss.rst renamed from Documentation/filesystems/nfs/rpc-server-gss.txt +11 -8
similarity index 92%
rename from Documentation/filesystems/nfs/rpc-server-gss.txt
rename to Documentation/filesystems/nfs/rpc-server-gss.rst
index 310bbbaf9080..812754576845 100644
@@ -1,4 +1,4 @@
-
+=========================================
 rpcsec_gss support for kernel RPC servers
 =========================================
 
@@ -9,14 +9,17 @@ NFSv4.1 and higher don't require the client to act as a server for the
 purposes of authentication.)
 
 RPCGSS is specified in a few IETF documents:
+
  - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt
  - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt
+
 and there is a 3rd version  being proposed:
+
  - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt
    (At draft n. 02 at the time of writing)
 
 Background
-----------
+==========
 
 The RPCGSS Authentication method describes a way to perform GSSAPI
 Authentication for NFS.  Although GSSAPI is itself completely mechanism
@@ -29,6 +32,7 @@ depends on GSSAPI extensions that are KRB5 specific.
 GSSAPI is a complex library, and implementing it completely in kernel is
 unwarranted. However GSSAPI operations are fundementally separable in 2
 parts:
+
 - initial context establishment
 - integrity/privacy protection (signing and encrypting of individual
   packets)
@@ -41,7 +45,7 @@ kernel, but leave the initial context establishment to userspace.  We
 need upcalls to request userspace to perform context establishment.
 
 NFS Server Legacy Upcall Mechanism
-----------------------------------
+==================================
 
 The classic upcall mechanism uses a custom text based upcall mechanism
 to talk to a custom daemon called rpc.svcgssd that is provide by the
@@ -62,21 +66,20 @@ groups) due to limitation on the size of the buffer that can be send
 back to the kernel (4KiB).
 
 NFS Server New RPC Upcall Mechanism
------------------------------------
+===================================
 
 The newer upcall mechanism uses RPC over a unix socket to a daemon
 called gss-proxy, implemented by a userspace program called Gssproxy.
 
-The gss_proxy RPC protocol is currently documented here:
-
-	https://fedorahosted.org/gss-proxy/wiki/ProtocolDocumentation
+The gss_proxy RPC protocol is currently documented `here
+<https://fedorahosted.org/gss-proxy/wiki/ProtocolDocumentation>`_.
 
 This upcall mechanism uses the kernel rpc client and connects to the gssproxy
 userspace program over a regular unix socket. The gssproxy protocol does not
 suffer from the size limitations of the legacy protocol.
 
 Negotiating Upcall Mechanisms
------------------------------
+=============================
 
 To provide backward compatibility, the kernel defaults to using the
 legacy mechanism.  To switch to the new mechanism, gss-proxy must bind
Signature · 1 line
2.25.0
#4 lore raw

PATCH v2 4/5 Documentation: nfs: nfs41-server: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert nfs41-server.txt to ReST. ASCII tables were converted to ReST grid table format.

---
 Documentation/filesystems/nfs/index.rst       |   1 +
 .../filesystems/nfs/nfs41-server.rst          | 256 ++++++++++++++++++
 .../filesystems/nfs/nfs41-server.txt          | 173 ------------
 3 files changed, 257 insertions(+), 173 deletions(-)
 create mode 100644 Documentation/filesystems/nfs/nfs41-server.rst
 delete mode 100644 Documentation/filesystems/nfs/nfs41-server.txt
Documentation/filesystems/nfs/index.rst +1 -0
index 9d5365cbe2c3..a0a678af921b 100644
@@ -9,3 +9,4 @@ NFS
    pnfs
    rpc-cache
    rpc-server-gss
+   nfs41-server
Documentation/filesystems/nfs/nfs41-server.rst new file +256 -0

256 lines not on this page · raw message

Documentation/filesystems/nfs/nfs41-server.txt deleted +0 -173

173 lines not on this page · raw message

Signature · 1 line
2.25.0
#5 lore raw

PATCH v2 5/5 Documentation: nfs: knfsd-stats: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert knfsd-stats.txt to ReST. Content remains mostly the same.

---
 Documentation/filesystems/nfs/index.rst         |  1 +
 .../nfs/{knfsd-stats.txt => knfsd-stats.rst}    | 17 ++++++++---------
 2 files changed, 9 insertions(+), 9 deletions(-)
 rename Documentation/filesystems/nfs/{knfsd-stats.txt => knfsd-stats.rst} (95%)
Documentation/filesystems/nfs/index.rst +1 -0
index a0a678af921b..65805624e39b 100644
@@ -10,3 +10,4 @@ NFS
    rpc-cache
    rpc-server-gss
    nfs41-server
+   knfsd-stats
Documentation/filesystems/nfs/knfsd-stats.rst renamed from Documentation/filesystems/nfs/knfsd-stats.txt +8 -9
similarity index 95%
rename from Documentation/filesystems/nfs/knfsd-stats.txt
rename to Documentation/filesystems/nfs/knfsd-stats.rst
index 1a5d82180b84..80bcf13550de 100644
@@ -1,7 +1,9 @@
-
+============================
 Kernel NFS Server Statistics
 ============================
 
+:Authors: Greg Banks <[email protected]> - 26 Mar 2009
+
 This document describes the format and semantics of the statistics
 which the kernel NFS server makes available to userspace.  These
 statistics are available in several text form pseudo files, each of
@@ -18,7 +20,7 @@ by parsing routines.  All other lines contain a sequence of fields
 separated by whitespace.
 
 /proc/fs/nfsd/pool_stats
-------------------------
+========================
 
 This file is available in kernels from 2.6.30 onwards, if the
 /proc/fs/nfsd filesystem is mounted (it almost always should be).
@@ -109,15 +111,12 @@ this case), or the transport can be enqueued for later attention
 (sockets-enqueued counts this case), or the packet can be temporarily
 deferred because the transport is currently being used by an nfsd
 thread.  This last case is not very interesting and is not explicitly
-counted, but can be inferred from the other counters thus:
+counted, but can be inferred from the other counters thus::
 
-packets-deferred = packets-arrived - ( sockets-enqueued + threads-woken )
+	packets-deferred = packets-arrived - ( sockets-enqueued + threads-woken )
 
 
 More
-----
-Descriptions of the other statistics file should go here.
-
+====
 
-Greg Banks <[email protected]>
-26 Mar 2009
+Descriptions of the other statistics file should go here.
Signature · 1 line
2.25.0
maintainer Applied
#6 lore raw
In reply to Daniel W. S. Almeida
Quoted 12 lines · On Wed, 29 Jan 2020 01:49:12 -0300 "Daniel W. S. Almeida"…

From: "Daniel W. S. Almeida" <[email protected]>

This series completes the conversion of Documentation/filesystems/nfs to ReST.

I did not think these rst files were supposed to be in admin-guide, so I left them where they are.

Changes in v2:
Change csv-table to ReST grid table format Remove "#." syntax

Quoted 6 lines

Daniel W. S. Almeida (5):
Documentation: nfs: convert pnfs.txt to ReST
Documentation: nfs: rpc-cache: convert to ReST
Documentation: nfs: rpc-server-gss: convert to ReST
Documentation: nfs: nfs41-server: convert to ReST
Documentation: nfs: knfsd-stats: convert to ReST

I've applied the set, thanks.

jon