On Fri, Jun 28, 2019 at 02:51:06PM -0700, Matthew Wilcox wrote:
> On Fri, Jun 28, 2019 at 10:43:02PM +0100, Sheriff Esseson wrote:
> > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > Documentation/index.rst.
>
> Didn't get_maintainers.pl suggest that you cc the linux-xfs mailing list?
No, because we suck. :(
> You also need to update MAINTAINERS.
Yes, please. :)
> > While at it, make "value" in "option=value" form xfs options definable by
> > the user, by embedding in angle "<>" brackets, rather than something
> > predifined elsewhere. This is inline with the conventions in manuals.
> >
> > Also, make defaults of boolean options prefixed with "(*)". This is
> > so that options can be compressed to "[no]option" and on a single line, which renders
> > consistently and nicely in htmldocs.
> > lastly, enforce a "one option, one definition" policy to keep things
> > consistent and simple.
> >
> > Signed-off-by: Sheriff Esseson <sheriffesseson@xxxxxxxxx>
> > ---
> > Documentation/filesystems/index.rst | 1 +
> > .../filesystems/{xfs.txt => xfs.rst} | 190 ++++++++++--------
> > 2 files changed, 103 insertions(+), 88 deletions(-)
> > rename Documentation/filesystems/{xfs.txt => xfs.rst} (74%)
> >
> > diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> > index 1131c34d7..be91fe616 100644
> > --- a/Documentation/filesystems/index.rst
> > +++ b/Documentation/filesystems/index.rst
> > @@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
> > :maxdepth: 2
> >
> > binderfs.rst
> > + xfs.rst
>
> I believe the convention is to not include the .rst suffix (and yes,
> binderfs is wrong here).
>
> > diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
> > similarity index 74%
> > rename from Documentation/filesystems/xfs.txt
> > rename to Documentation/filesystems/xfs.rst
> > index a5cbb5e0e..5e29e1583 100644
> > --- a/Documentation/filesystems/xfs.txt
> > +++ b/Documentation/filesystems/xfs.rst
> > @@ -1,4 +1,4 @@
> > -
> > +======================
> > The SGI XFS Filesystem
> > ======================
> >
> > @@ -18,10 +18,10 @@ Mount Options
> > =============
> >
> > When mounting an XFS filesystem, the following options are accepted.
> > -For boolean mount options, the names with the (*) suffix is the
> > +For boolean mount options, the names with the "(*)" prefix is the
> > default behaviour.
> >
> > - allocsize=size
> > + allocsize=<size>
> > Sets the buffered I/O end-of-file preallocation size when
> > doing delayed allocation writeout (default size is 64KiB).
> > Valid values for this option are page size (typically 4KiB)
> > @@ -34,181 +34,195 @@ default behaviour.
> > to the file. Specifying a fixed allocsize value turns off
> > the dynamic behaviour.
> >
> > - attr2
> > - noattr2
> > + [no]attr2
> > The options enable/disable an "opportunistic" improvement to
> > be made in the way inline extended attributes are stored
> > on-disk. When the new form is used for the first time when
> > - attr2 is selected (either when setting or removing extended
> > + ``attr2`` is selected (either when setting or removing extended
> > attributes) the on-disk superblock feature bit field will be
> > updated to reflect this format being in use.
> >
> > The default behaviour is determined by the on-disk feature
> > - bit indicating that attr2 behaviour is active. If either
> > - mount option it set, then that becomes the new default used
> > - by the filesystem.
> > -
> > - CRC enabled filesystems always use the attr2 format, and so
> > - will reject the noattr2 mount option if it is set.
> > + bit indicating that ``attr2`` behaviour is active. If either
> > + mount options is set, then that becomes the new default used
"If either mount option is set..."
> > + by the filesystem. However on CRC enabled filesystems, the
> > + ``attr2`` format is always used , and so
> > + will reject the ``noattr2`` mount option if it is set.
> >
> > - discard
> > - nodiscard (*)
> > + (*)[no]discard
> > Enable/disable the issuing of commands to let the block
> > device reclaim space freed by the filesystem. This is
> > useful for SSD devices, thinly provisioned LUNs and virtual
> > machine images, but may have a performance impact.
> >
> > - Note: It is currently recommended that you use the fstrim
> > - application to discard unused blocks rather than the discard
> > + Note: It is currently recommended that you use the ``fstrim``
> > + application to discard unused blocks rather than the ``discard``
> > mount option because the performance impact of this option
> > is quite severe.
> >
> > - grpid/bsdgroups
> > - nogrpid/sysvgroups (*)
> > + grpid/bsdgroups
> > + nogrpid/(*)sysvgroups
> > These options define what group ID a newly created file
> > - gets. When grpid is set, it takes the group ID of the
> > + gets. When ``grpid`` is set, it takes the group ID of the
> > directory in which it is created; otherwise it takes the
> > - fsgid of the current process, unless the directory has the
> > - setgid bit set, in which case it takes the gid from the
> > - parent directory, and also gets the setgid bit set if it is
> > + ``fsgid`` of the current process, unless the directory has the
> > + ``setgid`` bit set, in which case it takes the ``gid`` from the
> > + parent directory, and also gets the ``setgid`` bit set if it is
> > a directory itself.
> >
> > - filestreams
> > + filestreams
> > Make the data allocator use the filestreams allocation mode
> > across the entire filesystem rather than just on directories
> > configured to use it.
> >
> > - ikeep
> > - noikeep (*)
> > - When ikeep is specified, XFS does not delete empty inode
> > - clusters and keeps them around on disk. When noikeep is
> > + (*)[no]ikeep
> > + When ``ikeep`` is specified, XFS does not delete empty inode
> > + clusters and keeps them around on disk. When ``noikeep`` is
> > specified, empty inode clusters are returned to the free
> > space pool.
> >
> > - inode32
> > - inode64 (*)
> > - When inode32 is specified, it indicates that XFS limits
> > + inode32 | (*)inode64
> > + When ``inode32`` is specified, it indicates that XFS limits
> > inode creation to locations which will not result in inode
> > numbers with more than 32 bits of significance.
> >
> > - When inode64 is specified, it indicates that XFS is allowed
> > + When ``inode64`` is specified, it indicates that XFS is allowed
> > to create inodes at any location in the filesystem,
> > including those which will result in inode numbers occupying
> > - more than 32 bits of significance.
> > + more than 32 bits of significance.
> >
> > - inode32 is provided for backwards compatibility with older
> > + ``inode32`` is provided for backwards compatibility with older
> > systems and applications, since 64 bits inode numbers might
> > cause problems for some applications that cannot handle
> > large inode numbers. If applications are in use which do
> > - not handle inode numbers bigger than 32 bits, the inode32
> > + not handle inode numbers bigger than 32 bits, the ``inode32``
> > option should be specified.
> >
> >
> > - largeio
> > - nolargeio (*)
> > - If "nolargeio" is specified, the optimal I/O reported in
> > - st_blksize by stat(2) will be as small as possible to allow
> > + (*)[no]largeio
> > + If ``nolargeio`` is specified, the optimal I/O reported in
> > + st_blksize by **stat(2)** will be as small as possible to allow
> > user applications to avoid inefficient read/modify/write
> > I/O. This is typically the page size of the machine, as
> > this is the granularity of the page cache.
> >
> > - If "largeio" specified, a filesystem that was created with a
> > - "swidth" specified will return the "swidth" value (in bytes)
> > - in st_blksize. If the filesystem does not have a "swidth"
> > - specified but does specify an "allocsize" then "allocsize"
> > + If ``largeio`` specified, a filesystem that was created with a
"If ``largeio`` is specified..."
> > + ``swidth`` specified will return the ``swidth`` value (in bytes)
> > + in st_blksize. If the filesystem does not have a ``swidth``
> > + specified but does specify an ``allocsize`` then ``allocsize``
> > (in bytes) will be returned instead. Otherwise the behaviour
> > - is the same as if "nolargeio" was specified.
> > + is the same as if ``nolargeio`` was specified.
> >
> > - logbufs=value
> > - Set the number of in-memory log buffers. Valid numbers
> > + logbufs=<value>
> > + Set the number of in-memory log buffers to ``value``. Valid numbers
> > range from 2-8 inclusive.
> >
> > The default value is 8 buffers.
> >
> > If the memory cost of 8 log buffers is too high on small
> > systems, then it may be reduced at some cost to performance
> > - on metadata intensive workloads. The logbsize option below
> > + on metadata intensive workloads. The ``logbsize`` option below
> > controls the size of each buffer and so is also relevant to
> > this case.
> >
> > - logbsize=value
> > - Set the size of each in-memory log buffer. The size may be
> > - specified in bytes, or in kilobytes with a "k" suffix.
> > + logbsize=<value>
> > + Set the size of each in-memory log buffer to ``value``. The size
> > + may be specified in bytes, or in kilobytes with a "k" suffix.
Why the indentation here?
> > Valid sizes for version 1 and version 2 logs are 16384 (16k)
> > and 32768 (32k). Valid sizes for version 2 logs also
> > include 65536 (64k), 131072 (128k) and 262144 (256k). The
> > - logbsize must be an integer multiple of the log
> > - stripe unit configured at mkfs time.
> > + ``logbsize`` must be an integer multiple of the
> > + "log stripe unit" configured at mkfs time.
Or here?
> >
> > The default value for for version 1 logs is 32768, while the
> > - default value for version 2 logs is MAX(32768, log_sunit).
> > + default value for version 2 logs is ``MAX(32768, log_sunit)``.
> >
> > - logdev=device and rtdev=device
> > - Use an external log (metadata journal) and/or real-time device.
> > - An XFS filesystem has up to three parts: a data section, a log
> > - section, and a real-time section. The real-time section is
> > - optional, and the log section can be separate from the data
> > - section or contained within it.
> > + logdev=<device>
> > + Use ``device`` as an external log.
"...as an external log (metadata journal)."
> > + In an XFS filesystem, the log section can be separate from
> > + the data section or contained within it.
s/section/device/
Hmm, maybe it's time to just call them devices like everyone else on
Linux does. I'd guess "section" is a holdover from IRIX(?)
> >
> > - noalign
> > + rtdev=<device>
> > + An XFS filesystem has up to three parts: a data section, a log
> > + section, and a real-time section. The real-time section is optional.
> > + If enabled, ``rtdev`` sets ``device`` to be used as an
> > + external real-time section, similar to ``logdev`` above.
Why indent here?
> > + noalign
> > Data allocations will not be aligned at stripe unit
> > boundaries. This is only relevant to filesystems created
> > with non-zero data alignment parameters (sunit, swidth) by
> > mkfs.
> >
> > - norecovery
> > + norecovery
> > The filesystem will be mounted without running log recovery.
> > If the filesystem was not cleanly unmounted, it is likely to
> > - be inconsistent when mounted in "norecovery" mode.
> > + be inconsistent when mounted in ``norecovery`` mode.
> > Some files or directories may not be accessible because of this.
> > - Filesystems mounted "norecovery" must be mounted read-only or
> > + Filesystems mounted ``norecovery`` must be mounted read-only or
> > the mount will fail.
> >
> > - nouuid
> > + nouuid
> > Don't check for double mounted file systems using the file
> > system uuid. This is useful to mount LVM snapshot volumes,
> > - and often used in combination with "norecovery" for mounting
> > + and often used in combination with ``norecovery`` for mounting
> > read-only snapshots.
> >
> > - noquota
> > + noquota
> > Forcibly turns off all quota accounting and enforcement
> > within the filesystem.
> >
> > - uquota/usrquota/uqnoenforce/quota
> > + uquota/usrquota/uqnoenforce/quota
> > User disk quota accounting enabled, and limits (optionally)
> > - enforced. Refer to xfs_quota(8) for further details.
> > + enforced. Refer to **xfs_quota(8)** for further details.
> >
> > - gquota/grpquota/gqnoenforce
> > + gquota/grpquota/gqnoenforce
> > Group disk quota accounting enabled and limits (optionally)
> > - enforced. Refer to xfs_quota(8) for further details.
> > + enforced. Refer to **xfs_quota(8)** for further details.
> >
> > - pquota/prjquota/pqnoenforce
> > + pquota/prjquota/pqnoenforce
> > Project disk quota accounting enabled and limits (optionally)
> > - enforced. Refer to xfs_quota(8) for further details.
> > + enforced. Refer to **xfs_quota(8)** for further details.
> >
> > - sunit=value and swidth=value
> > - Used to specify the stripe unit and width for a RAID device
> > - or a stripe volume. "value" must be specified in 512-byte
> > - block units. These options are only relevant to filesystems
> > + sunit=<value>
> > + Used to specify the stripe unit for a RAID device
> > + or (in conjunction with ``swidth`` below) a stripe volume. ``value`` must be specified in 512-byte
Long line?
> > + block units. This option is only relevant to filesystems
> > that were created with non-zero data alignment parameters.
> >
> > - The sunit and swidth parameters specified must be compatible
> > + The ``sunit`` parameter specified must be compatible
> > with the existing filesystem alignment characteristics. In
> > - general, that means the only valid changes to sunit are
> > - increasing it by a power-of-2 multiple. Valid swidth values
> > - are any integer multiple of a valid sunit value.
> > + general, that means the only valid changes to ``sunit`` are
> > + increasing it by a power-of-2 multiple.
> >
> > - Typically the only time these mount options are necessary if
> > - after an underlying RAID device has had it's geometry
> > + Typically, this mount option is necessary only
> > + after an underlying RAID device has had its geometry
> > modified, such as adding a new disk to a RAID5 lun and
> > reshaping it.
> >
> > - swalloc
> > + swidth=<value>
> > + Used to specify the stripe width for a RAID device
> > + or (in conjunction with ``sunit`` above) a stripe volume. ``value`` must be specified in 512-byte
Line too long.
> > + block units. This option, like ``sunit`` above, is only
> > + relevant to filesystems that were created with non-zero data alignment parameters.
Why indent here?
> > +
> > + The ``swidth`` parameter specified must be compatible
> > + with the existing filesystem alignment characteristics. In
> > + general, that means the only valid swidth values
> > + are any integer multiple of a valid ``sunit`` value.
> > +
> > + Typically, this mount option is necessary only
> > + after an underlying RAID device has had its geometry
> > + modified, such as adding a new disk to a RAID5 lun and
> > + reshaping it.
> > +
> > +
> > + swalloc
> > Data allocations will be rounded up to stripe width boundaries
> > when the current end of file is being extended and the file
> > size is larger than the stripe width size.
> >
> > - wsync
> > + wsync
> > When specified, all filesystem namespace operations are
> > executed synchronously. This ensures that when the namespace
> > operation (create, unlink, etc) completes, the change to the
> > @@ -302,27 +316,27 @@ The following sysctls are available for the XFS filesystem:
> >
> > fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
> > Setting this to "1" will cause the "sync" flag set
> > - by the xfs_io(8) chattr command on a directory to be
> > + by the **xfs_io(8)** chattr command on a directory to be
> > inherited by files in that directory.
> >
> > fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
> > Setting this to "1" will cause the "nodump" flag set
> > - by the xfs_io(8) chattr command on a directory to be
> > + by the **xfs_io(8)** chattr command on a directory to be
> > inherited by files in that directory.
> >
> > fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
> > Setting this to "1" will cause the "noatime" flag set
> > - by the xfs_io(8) chattr command on a directory to be
> > + by the **xfs_io(8)** chattr command on a directory to be
> > inherited by files in that directory.
> >
> > fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
> > Setting this to "1" will cause the "nosymlinks" flag set
> > - by the xfs_io(8) chattr command on a directory to be
> > + by the **xfs_io(8)** chattr command on a directory to be
> > inherited by files in that directory.
> >
> > fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
> > Setting this to "1" will cause the "nodefrag" flag set
> > - by the xfs_io(8) chattr command on a directory to be
> > + by the **xfs_io(8)** chattr command on a directory to be
> > inherited by files in that directory.
Otherwise, this looks good. Thank you for taking on this conversion!
--D
> >
> > fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
> > --
> > 2.22.0
> >
