* Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands
From: Andy Shevchenko @ 2019-06-29 16:03 UTC (permalink / raw)
To: Srinivas Pandruvada
Cc: Darren Hart, Andy Shevchenko, Andriy Shevchenko, Jonathan Corbet,
Rafael J. Wysocki, Alan Cox, Len Brown, prarit, darcari,
Linux Documentation List, Linux Kernel Mailing List,
Platform Driver
In-Reply-To: <1c4238f7d18d316df82d3ba1618fecdcf014f98a.camel@linux.intel.com>
On Sat, Jun 29, 2019 at 5:53 PM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
> On Sat, 2019-06-29 at 17:31 +0300, Andy Shevchenko wrote:
> > On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
> > <srinivas.pandruvada@linux.intel.com> wrote:
> > I need an Ack from tools/power maintainer(s) for this.
> > Also see below.
> MAINTAINER file doesn't call for any special name in this folder.
And this tells me perhaps this driver needs a MAINTAINER record?
> $./scripts/get_maintainer.pl 0010-tools-power-x86-A-tool-to-validate-
> Intel-Speed-Selec.patch
> Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:31/31=100%,added_
> lines:231/231=100%,added_lines:1607/1607=100%,added_lines:721/721=100%,
> added_lines:479/479=100%)
> linux-kernel@vger.kernel.org (open list)
>
> Len and Rafael can you ACK this tool patch?
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Mauro Carvalho Chehab @ 2019-06-29 16:02 UTC (permalink / raw)
To: Vandana BN
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <4549aead-e916-a889-6c18-f695086fb72c@gmail.com>
Em Sat, 29 Jun 2019 21:26:29 +0530
Vandana BN <bnvandana@gmail.com> escreveu:
> On 29/06/19 8:20 PM, Mauro Carvalho Chehab wrote:
> > Em Sat, 29 Jun 2019 20:02:45 +0530
> > Vandana BN <bnvandana@gmail.com> escreveu:
> >
> >> This patch converts new-machine.txt and register-banks.txt
> >> to ReST format, No content change.
> >> Added interfaces.rst to contain kernel-doc markups from index.rst
> >> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
> >> Added SPDX tag in index.rst
> >>
> >> Signed-off-by: Vandana BN <bnvandana@gmail.com>
> > Looks good to me. Just a final thing to do.
> >
> > Be sure to run:
> >
> > ./scripts/documentation-file-ref-check
> >
> > in order to check that you're not breaking any references to the file.
> > If it breaks, please adjust the reference to reflect the file
> > rename.
> >
> > After fixing the broken reference, feel free do add:
> >
> > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>
> Thanks Mauro,
>
> i don't not see any broken references.
Then maybe the script is broken. A simple grep here (linux-next) shows
one such reference:
git grep Documentation/sh/
MAINTAINERS:F: Documentation/sh/
arch/sh/Kconfig.cpu: See <file:Documentation/sh/register-banks.txt> for further
>
> >> ---
> >> Documentation/sh/index.rst | 65 +------
> >> Documentation/sh/interface.rst | 59 ++++++
> >> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
> >> ...{register-banks.txt => register-banks.rst} | 8 +-
> >> 4 files changed, 163 insertions(+), 140 deletions(-)
> >> create mode 100644 Documentation/sh/interface.rst
> >> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
> >> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
> >>
> >> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
> >> index bc8db7ba894a..fec3c405b6b9 100644
> >> --- a/Documentation/sh/index.rst
> >> +++ b/Documentation/sh/index.rst
> >> @@ -1,59 +1,14 @@
> >> -=======================
> >> -SuperH Interfaces Guide
> >> -=======================
> >> +.. SPDX-License-Identifier: GPL-2.0
> >>
> >> -:Author: Paul Mundt
> >> -
> >> -Memory Management
> >> -=================
> >> -
> >> -SH-4
> >> -----
> >> -
> >> -Store Queue API
> >> -~~~~~~~~~~~~~~~
> >> -
> >> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> >> - :export:
> >> -
> >> -SH-5
> >> -----
> >> -
> >> -TLB Interfaces
> >> -~~~~~~~~~~~~~~
> >> -
> >> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> >> - :internal:
> >> -
> >> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> >> - :internal:
> >> +====================
> >> +SuperH Documentation
> >> +====================
> >>
> >> -Machine Specific Interfaces
> >> -===========================
> >> -
> >> -mach-dreamcast
> >> ---------------
> >> -
> >> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> >> - :internal:
> >> -
> >> -mach-x3proto
> >> -------------
> >> -
> >> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> >> - :export:
> >> -
> >> -Busses
> >> -======
> >> -
> >> -SuperHyway
> >> -----------
> >> -
> >> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> >> - :export:
> >> +:Author: Paul Mundt
> >>
> >> -Maple
> >> ------
> >> +.. toctree::
> >> + :maxdepth: 2
> >>
> >> -.. kernel-doc:: drivers/sh/maple/maple.c
> >> - :export:
> >> + interface
> >> + new-machine
> >> + register-banks
> >> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
> >> new file mode 100644
> >> index 000000000000..bc8db7ba894a
> >> --- /dev/null
> >> +++ b/Documentation/sh/interface.rst
> >> @@ -0,0 +1,59 @@
> >> +=======================
> >> +SuperH Interfaces Guide
> >> +=======================
> >> +
> >> +:Author: Paul Mundt
> >> +
> >> +Memory Management
> >> +=================
> >> +
> >> +SH-4
> >> +----
> >> +
> >> +Store Queue API
> >> +~~~~~~~~~~~~~~~
> >> +
> >> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> >> + :export:
> >> +
> >> +SH-5
> >> +----
> >> +
> >> +TLB Interfaces
> >> +~~~~~~~~~~~~~~
> >> +
> >> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> >> + :internal:
> >> +
> >> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> >> + :internal:
> >> +
> >> +Machine Specific Interfaces
> >> +===========================
> >> +
> >> +mach-dreamcast
> >> +--------------
> >> +
> >> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> >> + :internal:
> >> +
> >> +mach-x3proto
> >> +------------
> >> +
> >> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> >> + :export:
> >> +
> >> +Busses
> >> +======
> >> +
> >> +SuperHyway
> >> +----------
> >> +
> >> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> >> + :export:
> >> +
> >> +Maple
> >> +-----
> >> +
> >> +.. kernel-doc:: drivers/sh/maple/maple.c
> >> + :export:
> >> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
> >> similarity index 79%
> >> rename from Documentation/sh/new-machine.txt
> >> rename to Documentation/sh/new-machine.rst
> >> index e0961a66130b..b16c33342642 100644
> >> --- a/Documentation/sh/new-machine.txt
> >> +++ b/Documentation/sh/new-machine.rst
> >> @@ -1,8 +1,8 @@
> >> +================================
> >> +Adding a new board to LinuxSH
> >> +================================
> >>
> >> - Adding a new board to LinuxSH
> >> - ================================
> >> -
> >> - Paul Mundt <lethal@linux-sh.org>
> >> +Paul Mundt <lethal@linux-sh.org>
> >>
> >> This document attempts to outline what steps are necessary to add support
> >> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
> >> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
> >> companion chip type, and CPU type. Looking at a tree view of this directory
> >> hierarchy looks like the following:
> >>
> >> -Board-specific code:
> >> -
> >> -.
> >> -|-- arch
> >> -| `-- sh
> >> -| `-- boards
> >> -| |-- adx
> >> -| | `-- board-specific files
> >> -| |-- bigsur
> >> -| | `-- board-specific files
> >> -| |
> >> -| ... more boards here ...
> >> -|
> >> -`-- include
> >> - `-- asm-sh
> >> - |-- adx
> >> - | `-- board-specific headers
> >> - |-- bigsur
> >> - | `-- board-specific headers
> >> - |
> >> - .. more boards here ...
> >> -
> >> -Next, for companion chips:
> >> -.
> >> -`-- arch
> >> - `-- sh
> >> - `-- cchips
> >> - `-- hd6446x
> >> - `-- hd64461
> >> - `-- cchip-specific files
> >> +Board-specific code::
> >> +
> >> + .
> >> + |-- arch
> >> + | `-- sh
> >> + | `-- boards
> >> + | |-- adx
> >> + | | `-- board-specific files
> >> + | |-- bigsur
> >> + | | `-- board-specific files
> >> + | |
> >> + | ... more boards here ...
> >> + |
> >> + `-- include
> >> + `-- asm-sh
> >> + |-- adx
> >> + | `-- board-specific headers
> >> + |-- bigsur
> >> + | `-- board-specific headers
> >> + |
> >> + .. more boards here ...
> >> +
> >> +Next, for companion chips::
> >> +
> >> + .
> >> + `-- arch
> >> + `-- sh
> >> + `-- cchips
> >> + `-- hd6446x
> >> + `-- hd64461
> >> + `-- cchip-specific files
> >>
> >> ... and so on. Headers for the companion chips are treated the same way as
> >> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
> >> hd64461-specific headers.
> >>
> >> -Finally, CPU family support is also abstracted:
> >> -.
> >> -|-- arch
> >> -| `-- sh
> >> -| |-- kernel
> >> -| | `-- cpu
> >> -| | |-- sh2
> >> -| | | `-- SH-2 generic files
> >> -| | |-- sh3
> >> -| | | `-- SH-3 generic files
> >> -| | `-- sh4
> >> -| | `-- SH-4 generic files
> >> -| `-- mm
> >> -| `-- This is also broken out per CPU family, so each family can
> >> -| have their own set of cache/tlb functions.
> >> -|
> >> -`-- include
> >> - `-- asm-sh
> >> - |-- cpu-sh2
> >> - | `-- SH-2 specific headers
> >> - |-- cpu-sh3
> >> - | `-- SH-3 specific headers
> >> - `-- cpu-sh4
> >> - `-- SH-4 specific headers
> >> +Finally, CPU family support is also abstracted::
> >> +
> >> + .
> >> + |-- arch
> >> + | `-- sh
> >> + | |-- kernel
> >> + | | `-- cpu
> >> + | | |-- sh2
> >> + | | | `-- SH-2 generic files
> >> + | | |-- sh3
> >> + | | | `-- SH-3 generic files
> >> + | | `-- sh4
> >> + | | `-- SH-4 generic files
> >> + | `-- mm
> >> + | `-- This is also broken out per CPU family, so each family can
> >> + | have their own set of cache/tlb functions.
> >> + |
> >> + `-- include
> >> + `-- asm-sh
> >> + |-- cpu-sh2
> >> + | `-- SH-2 specific headers
> >> + |-- cpu-sh3
> >> + | `-- SH-3 specific headers
> >> + `-- cpu-sh4
> >> + `-- SH-4 specific headers
> >>
> >> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
> >> need to be dealt with by the CPU family specific code.
> >> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
> >> get_system_type() and platform_setup(). For our imaginary board, this
> >> might look something like:
> >>
> >> -/*
> >> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> >> - */
> >> -#include <linux/init.h>
> >> +.. code-block:: c
> >> +
> >> + /*
> >> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> >> + */
> >> + #include <linux/init.h>
> >>
> >> -const char *get_system_type(void)
> >> -{
> >> - return "FooTech Vaporboard";
> >> -}
> >> + const char *get_system_type(void)
> >> + {
> >> + return "FooTech Vaporboard";
> >> + }
> >>
> >> -int __init platform_setup(void)
> >> -{
> >> + int __init platform_setup(void)
> >> + {
> >> /*
> >> * If our hardware actually existed, we would do real
> >> * setup here. Though it's also sane to leave this empty
> >> @@ -136,7 +140,8 @@ int __init platform_setup(void)
> >> /* And whatever else ... */
> >>
> >> return 0;
> >> -}
> >> + }
> >> +
> >>
> >> Our new imaginary board will also have to tie into the machvec in order for it
> >> to be of any use.
> >> @@ -172,16 +177,17 @@ sufficient.
> >> vector.
> >>
> >> Note that these prototypes are generated automatically by setting
> >> - __IO_PREFIX to something sensible. A typical example would be:
> >> + __IO_PREFIX to something sensible. A typical example would be::
> >>
> >> #define __IO_PREFIX vapor
> >> #include <asm/io_generic.h>
> >>
> >> +
> >> somewhere in the board-specific header. Any boards being ported that still
> >> have a legacy io.h should remove it entirely and switch to the new model.
> >>
> >> - Add machine vector definitions to the board's setup.c. At a bare minimum,
> >> - this must be defined as something like:
> >> + this must be defined as something like::
> >>
> >> struct sh_machine_vector mv_vapor __initmv = {
> >> .mv_name = "vapor",
> >> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
> >> require the proper entry here and there in order to get things done.
> >>
> >> The first thing to do is to add an entry to arch/sh/Kconfig, under the
> >> -"System type" menu:
> >> +"System type" menu::
> >>
> >> -config SH_VAPOR
> >> - bool "Vapor"
> >> - help
> >> + config SH_VAPOR
> >> + bool "Vapor"
> >> + help
> >> select Vapor if configuring for a FooTech Vaporboard.
> >>
> >> next, this has to be added into arch/sh/Makefile. All boards require a
> >> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
> >> implicit checks for your board if you need this somewhere throughout the
> >> common code, such as:
> >>
> >> +::
> >> +
> >> /* Make sure we're on the FooTech Vaporboard */
> >> if (!mach_is_vapor())
> >> return -ENODEV;
> >> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
> >> Looking at the 'make help' output, you should now see something like:
> >>
> >> Architecture specific targets (sh):
> >> - zImage - Compressed kernel image (arch/sh/boot/zImage)
> >> - adx_defconfig - Build for adx
> >> - cqreek_defconfig - Build for cqreek
> >> - dreamcast_defconfig - Build for dreamcast
> >> -...
> >> - vapor_defconfig - Build for vapor
> >> +
> >> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
> >> + - adx_defconfig - Build for adx
> >> + - cqreek_defconfig - Build for cqreek
> >> + - dreamcast_defconfig - Build for dreamcast
> >> + - ...
> >> + - vapor_defconfig - Build for vapor
> >>
> >> which then allows you to do:
> >>
> >> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
> >> similarity index 90%
> >> rename from Documentation/sh/register-banks.txt
> >> rename to Documentation/sh/register-banks.rst
> >> index a6719f2f6594..acccfaf80355 100644
> >> --- a/Documentation/sh/register-banks.txt
> >> +++ b/Documentation/sh/register-banks.rst
> >> @@ -1,8 +1,9 @@
> >> - Notes on register bank usage in the kernel
> >> - ==========================================
> >> +==========================================
> >> +Notes on register bank usage in the kernel
> >> +==========================================
> >>
> >> Introduction
> >> -------------
> >> +============
> >>
> >> The SH-3 and SH-4 CPU families traditionally include a single partial register
> >> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
> >> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
> >> - The SR.IMASK interrupt handler makes use of this to set the
> >> interrupt priority level (used by local_irq_enable())
> >> - r7_bank (current)
> >> -
> >> --
> >> 2.17.1
> >>
> >
> >
> > Thanks,
> > Mauro
>
> Regards,
>
> Vandana.
>
Thanks,
Mauro
^ permalink raw reply
* Re: [linux-kernel-mentees] [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 16:02 UTC (permalink / raw)
To: skhan
Cc: linux-kernel-mentees, darrick.wong, linux-xfs, corbet, linux-doc,
linux-kernel
In-Reply-To: <20190629150155.GB10491@localhost>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v2:
Update MAINTAINERS. Fix indentation/long line issues. cc Darick and xfs mailist.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 467 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 471 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..f52046b96
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,467 @@
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ 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) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [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 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 is
+ set, then that becomes the new default used 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.
+
+ (*)[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`` mount
+ option because the performance impact of this option is quite severe.
+
+ 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 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 a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[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 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 to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``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`` option should be specified.
+
+
+ (*)[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`` is 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`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ 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 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 to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. 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.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ 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.
+
+ 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
+ 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. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ 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 read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ 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 block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ 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.
+
+ 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.
+
+ 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 block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ 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
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ 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
+ 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
+ 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
+ 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
+ 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
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- 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)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- 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
- 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.
-
- discard
- nodiscard (*)
- 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
- mount option because the performance impact of this option
- is quite severe.
-
- 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
- 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
- a directory itself.
-
- 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
- specified, empty inode clusters are returned to the free
- space pool.
-
- 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
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- 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
- 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
- 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"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. 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
- 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.
- 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.
-
- The default value for for version 1 logs is 32768, while the
- 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.
-
- 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
- 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.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- 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
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- 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
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters 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.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's 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
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- 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
- 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
- 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
- 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
- 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
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands
From: Andy Shevchenko @ 2019-06-29 16:00 UTC (permalink / raw)
To: Srinivas Pandruvada
Cc: Darren Hart, Andy Shevchenko, Andriy Shevchenko, Jonathan Corbet,
Rafael J. Wysocki, Alan Cox, Len Brown, prarit, darcari,
Linux Documentation List, Linux Kernel Mailing List,
Platform Driver
In-Reply-To: <1c4238f7d18d316df82d3ba1618fecdcf014f98a.camel@linux.intel.com>
On Sat, Jun 29, 2019 at 5:53 PM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
> On Sat, 2019-06-29 at 17:31 +0300, Andy Shevchenko wrote:
> > On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
> > <srinivas.pandruvada@linux.intel.com> wrote:
> > > +++ b/tools/power/x86/intel_speed_select/Makefile
> >
> > My experience with some tools are not good in order of their build
> > process.
> > Can this one use tools build infrastructure from the day 1?
> Can you give some pointers?
Sure.
At least simple ones are under tools/gpio, tools/iio, etc.
You may compare them to see what's different and what's common and
base Makefile here on that.
I dunno if there is any tool under tools/power to use that, it might
give an example of `descend` feature in Makefile.
> > > @@ -0,0 +1,31 @@
> > > +# SPDX-License-Identifier: GPL-2.0
> > > +CC = $(CROSS_COMPILE)gcc
> > > +BUILD_OUTPUT := $(CURDIR)
> > > +PREFIX ?= /usr
> > > +DESTDIR ?=
> > > +
> > > +override CFLAGS += -D__EXPORTED_HEADERS__ -Wall -D_GNU_SOURCE
> > > +override CFLAGS += -I$(CURDIR)/../../../../include/uapi/
> > > +override CFLAGS += -I$(CURDIR)/../../../../include/
> > > +
> > > +%: %.c
> > > + @mkdir -p $(BUILD_OUTPUT)
> > > + $(CC) $(CFLAGS) $< -o $(BUILD_OUTPUT)/$@ $(LDFLAGS)
> > > +
> > > +DEPS = isst.h
> > > +OBJ = isst_config.o isst_core.o isst_display.o
> > > +
> > > +%.o: %.c $(DEPS)
> > > + $(CC) -c -o $(BUILD_OUTPUT)/$@ $< $(CFLAGS)
> > > +
> > > +intel-speed-select: $(OBJ)
> > > + $(CC) -o $(BUILD_OUTPUT)/$@ $^ $(CFLAGS)
> > > +
> > > +.PHONY : clean
> > > +clean :
> > > + @rm -f $(BUILD_OUTPUT)/intel-speed-select
> > > + @rm -f $(BUILD_OUTPUT)/*.o
> > > +
> > > +install : intel-speed-select
> > > + install -d $(DESTDIR)$(PREFIX)/sbin
> > > + install $(BUILD_OUTPUT)/intel-speed-select
> > > $(DESTDIR)$(PREFIX)/sbin/intel-speed-select
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Vandana BN @ 2019-06-29 15:56 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <20190629115014.4aec058d@coco.lan>
On 29/06/19 8:20 PM, Mauro Carvalho Chehab wrote:
> Em Sat, 29 Jun 2019 20:02:45 +0530
> Vandana BN <bnvandana@gmail.com> escreveu:
>
>> This patch converts new-machine.txt and register-banks.txt
>> to ReST format, No content change.
>> Added interfaces.rst to contain kernel-doc markups from index.rst
>> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
>> Added SPDX tag in index.rst
>>
>> Signed-off-by: Vandana BN <bnvandana@gmail.com>
> Looks good to me. Just a final thing to do.
>
> Be sure to run:
>
> ./scripts/documentation-file-ref-check
>
> in order to check that you're not breaking any references to the file.
> If it breaks, please adjust the reference to reflect the file
> rename.
>
> After fixing the broken reference, feel free do add:
>
> Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Thanks Mauro,
i don't not see any broken references.
>> ---
>> Documentation/sh/index.rst | 65 +------
>> Documentation/sh/interface.rst | 59 ++++++
>> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
>> ...{register-banks.txt => register-banks.rst} | 8 +-
>> 4 files changed, 163 insertions(+), 140 deletions(-)
>> create mode 100644 Documentation/sh/interface.rst
>> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
>> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>>
>> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
>> index bc8db7ba894a..fec3c405b6b9 100644
>> --- a/Documentation/sh/index.rst
>> +++ b/Documentation/sh/index.rst
>> @@ -1,59 +1,14 @@
>> -=======================
>> -SuperH Interfaces Guide
>> -=======================
>> +.. SPDX-License-Identifier: GPL-2.0
>>
>> -:Author: Paul Mundt
>> -
>> -Memory Management
>> -=================
>> -
>> -SH-4
>> -----
>> -
>> -Store Queue API
>> -~~~~~~~~~~~~~~~
>> -
>> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>> - :export:
>> -
>> -SH-5
>> -----
>> -
>> -TLB Interfaces
>> -~~~~~~~~~~~~~~
>> -
>> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>> - :internal:
>> -
>> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>> - :internal:
>> +====================
>> +SuperH Documentation
>> +====================
>>
>> -Machine Specific Interfaces
>> -===========================
>> -
>> -mach-dreamcast
>> ---------------
>> -
>> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>> - :internal:
>> -
>> -mach-x3proto
>> -------------
>> -
>> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>> - :export:
>> -
>> -Busses
>> -======
>> -
>> -SuperHyway
>> -----------
>> -
>> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>> - :export:
>> +:Author: Paul Mundt
>>
>> -Maple
>> ------
>> +.. toctree::
>> + :maxdepth: 2
>>
>> -.. kernel-doc:: drivers/sh/maple/maple.c
>> - :export:
>> + interface
>> + new-machine
>> + register-banks
>> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
>> new file mode 100644
>> index 000000000000..bc8db7ba894a
>> --- /dev/null
>> +++ b/Documentation/sh/interface.rst
>> @@ -0,0 +1,59 @@
>> +=======================
>> +SuperH Interfaces Guide
>> +=======================
>> +
>> +:Author: Paul Mundt
>> +
>> +Memory Management
>> +=================
>> +
>> +SH-4
>> +----
>> +
>> +Store Queue API
>> +~~~~~~~~~~~~~~~
>> +
>> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>> + :export:
>> +
>> +SH-5
>> +----
>> +
>> +TLB Interfaces
>> +~~~~~~~~~~~~~~
>> +
>> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>> + :internal:
>> +
>> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>> + :internal:
>> +
>> +Machine Specific Interfaces
>> +===========================
>> +
>> +mach-dreamcast
>> +--------------
>> +
>> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>> + :internal:
>> +
>> +mach-x3proto
>> +------------
>> +
>> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>> + :export:
>> +
>> +Busses
>> +======
>> +
>> +SuperHyway
>> +----------
>> +
>> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>> + :export:
>> +
>> +Maple
>> +-----
>> +
>> +.. kernel-doc:: drivers/sh/maple/maple.c
>> + :export:
>> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
>> similarity index 79%
>> rename from Documentation/sh/new-machine.txt
>> rename to Documentation/sh/new-machine.rst
>> index e0961a66130b..b16c33342642 100644
>> --- a/Documentation/sh/new-machine.txt
>> +++ b/Documentation/sh/new-machine.rst
>> @@ -1,8 +1,8 @@
>> +================================
>> +Adding a new board to LinuxSH
>> +================================
>>
>> - Adding a new board to LinuxSH
>> - ================================
>> -
>> - Paul Mundt <lethal@linux-sh.org>
>> +Paul Mundt <lethal@linux-sh.org>
>>
>> This document attempts to outline what steps are necessary to add support
>> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
>> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
>> companion chip type, and CPU type. Looking at a tree view of this directory
>> hierarchy looks like the following:
>>
>> -Board-specific code:
>> -
>> -.
>> -|-- arch
>> -| `-- sh
>> -| `-- boards
>> -| |-- adx
>> -| | `-- board-specific files
>> -| |-- bigsur
>> -| | `-- board-specific files
>> -| |
>> -| ... more boards here ...
>> -|
>> -`-- include
>> - `-- asm-sh
>> - |-- adx
>> - | `-- board-specific headers
>> - |-- bigsur
>> - | `-- board-specific headers
>> - |
>> - .. more boards here ...
>> -
>> -Next, for companion chips:
>> -.
>> -`-- arch
>> - `-- sh
>> - `-- cchips
>> - `-- hd6446x
>> - `-- hd64461
>> - `-- cchip-specific files
>> +Board-specific code::
>> +
>> + .
>> + |-- arch
>> + | `-- sh
>> + | `-- boards
>> + | |-- adx
>> + | | `-- board-specific files
>> + | |-- bigsur
>> + | | `-- board-specific files
>> + | |
>> + | ... more boards here ...
>> + |
>> + `-- include
>> + `-- asm-sh
>> + |-- adx
>> + | `-- board-specific headers
>> + |-- bigsur
>> + | `-- board-specific headers
>> + |
>> + .. more boards here ...
>> +
>> +Next, for companion chips::
>> +
>> + .
>> + `-- arch
>> + `-- sh
>> + `-- cchips
>> + `-- hd6446x
>> + `-- hd64461
>> + `-- cchip-specific files
>>
>> ... and so on. Headers for the companion chips are treated the same way as
>> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
>> hd64461-specific headers.
>>
>> -Finally, CPU family support is also abstracted:
>> -.
>> -|-- arch
>> -| `-- sh
>> -| |-- kernel
>> -| | `-- cpu
>> -| | |-- sh2
>> -| | | `-- SH-2 generic files
>> -| | |-- sh3
>> -| | | `-- SH-3 generic files
>> -| | `-- sh4
>> -| | `-- SH-4 generic files
>> -| `-- mm
>> -| `-- This is also broken out per CPU family, so each family can
>> -| have their own set of cache/tlb functions.
>> -|
>> -`-- include
>> - `-- asm-sh
>> - |-- cpu-sh2
>> - | `-- SH-2 specific headers
>> - |-- cpu-sh3
>> - | `-- SH-3 specific headers
>> - `-- cpu-sh4
>> - `-- SH-4 specific headers
>> +Finally, CPU family support is also abstracted::
>> +
>> + .
>> + |-- arch
>> + | `-- sh
>> + | |-- kernel
>> + | | `-- cpu
>> + | | |-- sh2
>> + | | | `-- SH-2 generic files
>> + | | |-- sh3
>> + | | | `-- SH-3 generic files
>> + | | `-- sh4
>> + | | `-- SH-4 generic files
>> + | `-- mm
>> + | `-- This is also broken out per CPU family, so each family can
>> + | have their own set of cache/tlb functions.
>> + |
>> + `-- include
>> + `-- asm-sh
>> + |-- cpu-sh2
>> + | `-- SH-2 specific headers
>> + |-- cpu-sh3
>> + | `-- SH-3 specific headers
>> + `-- cpu-sh4
>> + `-- SH-4 specific headers
>>
>> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
>> need to be dealt with by the CPU family specific code.
>> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
>> get_system_type() and platform_setup(). For our imaginary board, this
>> might look something like:
>>
>> -/*
>> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>> - */
>> -#include <linux/init.h>
>> +.. code-block:: c
>> +
>> + /*
>> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>> + */
>> + #include <linux/init.h>
>>
>> -const char *get_system_type(void)
>> -{
>> - return "FooTech Vaporboard";
>> -}
>> + const char *get_system_type(void)
>> + {
>> + return "FooTech Vaporboard";
>> + }
>>
>> -int __init platform_setup(void)
>> -{
>> + int __init platform_setup(void)
>> + {
>> /*
>> * If our hardware actually existed, we would do real
>> * setup here. Though it's also sane to leave this empty
>> @@ -136,7 +140,8 @@ int __init platform_setup(void)
>> /* And whatever else ... */
>>
>> return 0;
>> -}
>> + }
>> +
>>
>> Our new imaginary board will also have to tie into the machvec in order for it
>> to be of any use.
>> @@ -172,16 +177,17 @@ sufficient.
>> vector.
>>
>> Note that these prototypes are generated automatically by setting
>> - __IO_PREFIX to something sensible. A typical example would be:
>> + __IO_PREFIX to something sensible. A typical example would be::
>>
>> #define __IO_PREFIX vapor
>> #include <asm/io_generic.h>
>>
>> +
>> somewhere in the board-specific header. Any boards being ported that still
>> have a legacy io.h should remove it entirely and switch to the new model.
>>
>> - Add machine vector definitions to the board's setup.c. At a bare minimum,
>> - this must be defined as something like:
>> + this must be defined as something like::
>>
>> struct sh_machine_vector mv_vapor __initmv = {
>> .mv_name = "vapor",
>> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
>> require the proper entry here and there in order to get things done.
>>
>> The first thing to do is to add an entry to arch/sh/Kconfig, under the
>> -"System type" menu:
>> +"System type" menu::
>>
>> -config SH_VAPOR
>> - bool "Vapor"
>> - help
>> + config SH_VAPOR
>> + bool "Vapor"
>> + help
>> select Vapor if configuring for a FooTech Vaporboard.
>>
>> next, this has to be added into arch/sh/Makefile. All boards require a
>> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
>> implicit checks for your board if you need this somewhere throughout the
>> common code, such as:
>>
>> +::
>> +
>> /* Make sure we're on the FooTech Vaporboard */
>> if (!mach_is_vapor())
>> return -ENODEV;
>> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
>> Looking at the 'make help' output, you should now see something like:
>>
>> Architecture specific targets (sh):
>> - zImage - Compressed kernel image (arch/sh/boot/zImage)
>> - adx_defconfig - Build for adx
>> - cqreek_defconfig - Build for cqreek
>> - dreamcast_defconfig - Build for dreamcast
>> -...
>> - vapor_defconfig - Build for vapor
>> +
>> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
>> + - adx_defconfig - Build for adx
>> + - cqreek_defconfig - Build for cqreek
>> + - dreamcast_defconfig - Build for dreamcast
>> + - ...
>> + - vapor_defconfig - Build for vapor
>>
>> which then allows you to do:
>>
>> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
>> similarity index 90%
>> rename from Documentation/sh/register-banks.txt
>> rename to Documentation/sh/register-banks.rst
>> index a6719f2f6594..acccfaf80355 100644
>> --- a/Documentation/sh/register-banks.txt
>> +++ b/Documentation/sh/register-banks.rst
>> @@ -1,8 +1,9 @@
>> - Notes on register bank usage in the kernel
>> - ==========================================
>> +==========================================
>> +Notes on register bank usage in the kernel
>> +==========================================
>>
>> Introduction
>> -------------
>> +============
>>
>> The SH-3 and SH-4 CPU families traditionally include a single partial register
>> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
>> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
>> - The SR.IMASK interrupt handler makes use of this to set the
>> interrupt priority level (used by local_irq_enable())
>> - r7_bank (current)
>> -
>> --
>> 2.17.1
>>
>
>
> Thanks,
> Mauro
Regards,
Vandana.
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Jonathan Corbet @ 2019-06-29 15:14 UTC (permalink / raw)
To: Sheriff Esseson
Cc: skhan, darrick.wong, linux-xfs, linux-doc, linux-kernel,
linux-kernel-mentees
In-Reply-To: <20190629150155.GB10491@localhost>
On Sat, 29 Jun 2019 16:01:55 +0100
Sheriff Esseson <sheriffesseson@gmail.com> wrote:
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> In v2.1:
> cc mentees list.
Please do us a favor?
1) Post each patch standalone, without quoted text, ready to be applied.
2) Wait a little while between postings so that you can address more than
one comment at a time.
OK, two favors - off-by-one errors are my specialty...:)
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 15:01 UTC (permalink / raw)
To: skhan
Cc: darrick.wong, linux-xfs, corbet, linux-doc, linux-kernel,
linux-kernel-mentees
In-Reply-To: <20190629145433.GA10491@localhost>
On Sat, Jun 29, 2019 at 03:54:33PM +0100, Sheriff Esseson wrote:
> On Sat, Jun 29, 2019 at 02:25:08AM +0100, Sheriff Esseson wrote:
> > On Fri, Jun 28, 2019 at 10:43:24PM +0100, Sheriff Esseson wrote:
> > > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > > Documentation/index.rst.
> > >
> > > 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@gmail.com>
> > > ---
> > > --
> > > 2.22.0
> > >
> >
> > Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
> >
> > CC xfs-list.
> >
> > Correct email indentation.
> >
> > Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> > ---
> > --
> > 2.22.0
> >
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> In v2:
> Update MAINTAINERS.
> fix indentation/long lines issues.
> cc Darick and xfs mailing list.
>
> --
> 2.22.0
>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v2.1:
cc mentees list.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 467 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 471 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..f52046b96
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,467 @@
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ 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) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [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 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 is
+ set, then that becomes the new default used 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.
+
+ (*)[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`` mount
+ option because the performance impact of this option is quite severe.
+
+ 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 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 a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[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 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 to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``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`` option should be specified.
+
+
+ (*)[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`` is 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`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ 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 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 to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. 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.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ 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.
+
+ 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
+ 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. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ 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 read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ 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 block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ 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.
+
+ 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.
+
+ 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 block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ 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
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ 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
+ 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
+ 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
+ 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
+ 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
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- 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)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- 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
- 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.
-
- discard
- nodiscard (*)
- 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
- mount option because the performance impact of this option
- is quite severe.
-
- 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
- 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
- a directory itself.
-
- 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
- specified, empty inode clusters are returned to the free
- space pool.
-
- 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
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- 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
- 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
- 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"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. 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
- 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.
- 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.
-
- The default value for for version 1 logs is 32768, while the
- 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.
-
- 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
- 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.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- 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
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- 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
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters 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.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's 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
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- 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
- 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
- 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
- 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
- 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
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH v7 1/2] fTPM: firmware TPM running in TEE
From: Sasha Levin @ 2019-06-29 15:01 UTC (permalink / raw)
To: Jarkko Sakkinen
Cc: peterhuewe, jgg, corbet, linux-kernel, linux-doc, linux-integrity,
linux-kernel, thiruan, bryankel, tee-dev, ilias.apalodimas,
sumit.garg, rdunlap
In-Reply-To: <673dd30d03e8ed9825bb46ef21b2efef015f6f2a.camel@linux.intel.com>
On Thu, Jun 27, 2019 at 02:31:35AM +0300, Jarkko Sakkinen wrote:
>On Tue, 2019-06-25 at 16:13 -0400, Sasha Levin wrote:
>> +static const uuid_t ftpm_ta_uuid =
>> + UUID_INIT(0xBC50D971, 0xD4C9, 0x42C4,
>> + 0x82, 0xCB, 0x34, 0x3F, 0xB7, 0xF3, 0x78, 0x96);
>> +
>> +/**
>> + * ftpm_tee_tpm_op_recv - retrieve fTPM response.
>> + *
>
>Should not have an empty line here.
>
>> + * @chip: the tpm_chip description as specified in driver/char/tpm/tpm.h.
>> + * @buf: the buffer to store data.
>> + * @count: the number of bytes to read.
Jarkko, w.r.t your comment above, there is an empty line between the
function name and variables in drivers/char/tpm, and in particular
tpm_crb.c which you authored and I used as reference. Do you want us to
diverge here?
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 14:54 UTC (permalink / raw)
To: skhan; +Cc: darrick.wong, linux-xfs, corbet, linux-doc, linux-kernel
In-Reply-To: <20190629010733.GA31770@localhost>
On Sat, Jun 29, 2019 at 02:25:08AM +0100, Sheriff Esseson wrote:
> On Fri, Jun 28, 2019 at 10:43:24PM +0100, Sheriff Esseson wrote:
> > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > Documentation/index.rst.
> >
> > 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@gmail.com>
> > ---
> > --
> > 2.22.0
> >
>
> Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
>
> CC xfs-list.
>
> Correct email indentation.
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
> --
> 2.22.0
>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v2:
Update MAINTAINERS.
fix indentation/long lines issues.
cc Darick and xfs mailing list.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 467 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 471 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..f52046b96
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,467 @@
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ 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) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [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 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 is
+ set, then that becomes the new default used 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.
+
+ (*)[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`` mount
+ option because the performance impact of this option is quite severe.
+
+ 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 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 a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[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 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 to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``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`` option should be specified.
+
+
+ (*)[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`` is 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`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ 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 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 to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. 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.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ 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.
+
+ 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
+ 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. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ 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 read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ 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 block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ 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.
+
+ 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.
+
+ 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 block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ 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
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ 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
+ 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
+ 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
+ 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
+ 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
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- 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)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- 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
- 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.
-
- discard
- nodiscard (*)
- 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
- mount option because the performance impact of this option
- is quite severe.
-
- 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
- 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
- a directory itself.
-
- 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
- specified, empty inode clusters are returned to the free
- space pool.
-
- 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
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- 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
- 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
- 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"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. 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
- 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.
- 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.
-
- The default value for for version 1 logs is 32768, while the
- 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.
-
- 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
- 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.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- 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
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- 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
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters 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.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's 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
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- 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
- 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
- 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
- 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
- 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
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Mauro Carvalho Chehab @ 2019-06-29 14:50 UTC (permalink / raw)
To: Vandana BN
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <20190629143245.3580-1-bnvandana@gmail.com>
Em Sat, 29 Jun 2019 20:02:45 +0530
Vandana BN <bnvandana@gmail.com> escreveu:
> This patch converts new-machine.txt and register-banks.txt
> to ReST format, No content change.
> Added interfaces.rst to contain kernel-doc markups from index.rst
> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
> Added SPDX tag in index.rst
>
> Signed-off-by: Vandana BN <bnvandana@gmail.com>
Looks good to me. Just a final thing to do.
Be sure to run:
./scripts/documentation-file-ref-check
in order to check that you're not breaking any references to the file.
If it breaks, please adjust the reference to reflect the file
rename.
After fixing the broken reference, feel free do add:
Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> Documentation/sh/index.rst | 65 +------
> Documentation/sh/interface.rst | 59 ++++++
> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
> ...{register-banks.txt => register-banks.rst} | 8 +-
> 4 files changed, 163 insertions(+), 140 deletions(-)
> create mode 100644 Documentation/sh/interface.rst
> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>
> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
> index bc8db7ba894a..fec3c405b6b9 100644
> --- a/Documentation/sh/index.rst
> +++ b/Documentation/sh/index.rst
> @@ -1,59 +1,14 @@
> -=======================
> -SuperH Interfaces Guide
> -=======================
> +.. SPDX-License-Identifier: GPL-2.0
>
> -:Author: Paul Mundt
> -
> -Memory Management
> -=================
> -
> -SH-4
> -----
> -
> -Store Queue API
> -~~~~~~~~~~~~~~~
> -
> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> - :export:
> -
> -SH-5
> -----
> -
> -TLB Interfaces
> -~~~~~~~~~~~~~~
> -
> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> - :internal:
> -
> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> - :internal:
> +====================
> +SuperH Documentation
> +====================
>
> -Machine Specific Interfaces
> -===========================
> -
> -mach-dreamcast
> ---------------
> -
> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> - :internal:
> -
> -mach-x3proto
> -------------
> -
> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> - :export:
> -
> -Busses
> -======
> -
> -SuperHyway
> -----------
> -
> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> - :export:
> +:Author: Paul Mundt
>
> -Maple
> ------
> +.. toctree::
> + :maxdepth: 2
>
> -.. kernel-doc:: drivers/sh/maple/maple.c
> - :export:
> + interface
> + new-machine
> + register-banks
> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
> new file mode 100644
> index 000000000000..bc8db7ba894a
> --- /dev/null
> +++ b/Documentation/sh/interface.rst
> @@ -0,0 +1,59 @@
> +=======================
> +SuperH Interfaces Guide
> +=======================
> +
> +:Author: Paul Mundt
> +
> +Memory Management
> +=================
> +
> +SH-4
> +----
> +
> +Store Queue API
> +~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> + :export:
> +
> +SH-5
> +----
> +
> +TLB Interfaces
> +~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> + :internal:
> +
> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> + :internal:
> +
> +Machine Specific Interfaces
> +===========================
> +
> +mach-dreamcast
> +--------------
> +
> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> + :internal:
> +
> +mach-x3proto
> +------------
> +
> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> + :export:
> +
> +Busses
> +======
> +
> +SuperHyway
> +----------
> +
> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> + :export:
> +
> +Maple
> +-----
> +
> +.. kernel-doc:: drivers/sh/maple/maple.c
> + :export:
> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
> similarity index 79%
> rename from Documentation/sh/new-machine.txt
> rename to Documentation/sh/new-machine.rst
> index e0961a66130b..b16c33342642 100644
> --- a/Documentation/sh/new-machine.txt
> +++ b/Documentation/sh/new-machine.rst
> @@ -1,8 +1,8 @@
> +================================
> +Adding a new board to LinuxSH
> +================================
>
> - Adding a new board to LinuxSH
> - ================================
> -
> - Paul Mundt <lethal@linux-sh.org>
> +Paul Mundt <lethal@linux-sh.org>
>
> This document attempts to outline what steps are necessary to add support
> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
> companion chip type, and CPU type. Looking at a tree view of this directory
> hierarchy looks like the following:
>
> -Board-specific code:
> -
> -.
> -|-- arch
> -| `-- sh
> -| `-- boards
> -| |-- adx
> -| | `-- board-specific files
> -| |-- bigsur
> -| | `-- board-specific files
> -| |
> -| ... more boards here ...
> -|
> -`-- include
> - `-- asm-sh
> - |-- adx
> - | `-- board-specific headers
> - |-- bigsur
> - | `-- board-specific headers
> - |
> - .. more boards here ...
> -
> -Next, for companion chips:
> -.
> -`-- arch
> - `-- sh
> - `-- cchips
> - `-- hd6446x
> - `-- hd64461
> - `-- cchip-specific files
> +Board-specific code::
> +
> + .
> + |-- arch
> + | `-- sh
> + | `-- boards
> + | |-- adx
> + | | `-- board-specific files
> + | |-- bigsur
> + | | `-- board-specific files
> + | |
> + | ... more boards here ...
> + |
> + `-- include
> + `-- asm-sh
> + |-- adx
> + | `-- board-specific headers
> + |-- bigsur
> + | `-- board-specific headers
> + |
> + .. more boards here ...
> +
> +Next, for companion chips::
> +
> + .
> + `-- arch
> + `-- sh
> + `-- cchips
> + `-- hd6446x
> + `-- hd64461
> + `-- cchip-specific files
>
> ... and so on. Headers for the companion chips are treated the same way as
> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
> hd64461-specific headers.
>
> -Finally, CPU family support is also abstracted:
> -.
> -|-- arch
> -| `-- sh
> -| |-- kernel
> -| | `-- cpu
> -| | |-- sh2
> -| | | `-- SH-2 generic files
> -| | |-- sh3
> -| | | `-- SH-3 generic files
> -| | `-- sh4
> -| | `-- SH-4 generic files
> -| `-- mm
> -| `-- This is also broken out per CPU family, so each family can
> -| have their own set of cache/tlb functions.
> -|
> -`-- include
> - `-- asm-sh
> - |-- cpu-sh2
> - | `-- SH-2 specific headers
> - |-- cpu-sh3
> - | `-- SH-3 specific headers
> - `-- cpu-sh4
> - `-- SH-4 specific headers
> +Finally, CPU family support is also abstracted::
> +
> + .
> + |-- arch
> + | `-- sh
> + | |-- kernel
> + | | `-- cpu
> + | | |-- sh2
> + | | | `-- SH-2 generic files
> + | | |-- sh3
> + | | | `-- SH-3 generic files
> + | | `-- sh4
> + | | `-- SH-4 generic files
> + | `-- mm
> + | `-- This is also broken out per CPU family, so each family can
> + | have their own set of cache/tlb functions.
> + |
> + `-- include
> + `-- asm-sh
> + |-- cpu-sh2
> + | `-- SH-2 specific headers
> + |-- cpu-sh3
> + | `-- SH-3 specific headers
> + `-- cpu-sh4
> + `-- SH-4 specific headers
>
> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
> need to be dealt with by the CPU family specific code.
> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
> get_system_type() and platform_setup(). For our imaginary board, this
> might look something like:
>
> -/*
> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> - */
> -#include <linux/init.h>
> +.. code-block:: c
> +
> + /*
> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> + */
> + #include <linux/init.h>
>
> -const char *get_system_type(void)
> -{
> - return "FooTech Vaporboard";
> -}
> + const char *get_system_type(void)
> + {
> + return "FooTech Vaporboard";
> + }
>
> -int __init platform_setup(void)
> -{
> + int __init platform_setup(void)
> + {
> /*
> * If our hardware actually existed, we would do real
> * setup here. Though it's also sane to leave this empty
> @@ -136,7 +140,8 @@ int __init platform_setup(void)
> /* And whatever else ... */
>
> return 0;
> -}
> + }
> +
>
> Our new imaginary board will also have to tie into the machvec in order for it
> to be of any use.
> @@ -172,16 +177,17 @@ sufficient.
> vector.
>
> Note that these prototypes are generated automatically by setting
> - __IO_PREFIX to something sensible. A typical example would be:
> + __IO_PREFIX to something sensible. A typical example would be::
>
> #define __IO_PREFIX vapor
> #include <asm/io_generic.h>
>
> +
> somewhere in the board-specific header. Any boards being ported that still
> have a legacy io.h should remove it entirely and switch to the new model.
>
> - Add machine vector definitions to the board's setup.c. At a bare minimum,
> - this must be defined as something like:
> + this must be defined as something like::
>
> struct sh_machine_vector mv_vapor __initmv = {
> .mv_name = "vapor",
> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
> require the proper entry here and there in order to get things done.
>
> The first thing to do is to add an entry to arch/sh/Kconfig, under the
> -"System type" menu:
> +"System type" menu::
>
> -config SH_VAPOR
> - bool "Vapor"
> - help
> + config SH_VAPOR
> + bool "Vapor"
> + help
> select Vapor if configuring for a FooTech Vaporboard.
>
> next, this has to be added into arch/sh/Makefile. All boards require a
> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
> implicit checks for your board if you need this somewhere throughout the
> common code, such as:
>
> +::
> +
> /* Make sure we're on the FooTech Vaporboard */
> if (!mach_is_vapor())
> return -ENODEV;
> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
> Looking at the 'make help' output, you should now see something like:
>
> Architecture specific targets (sh):
> - zImage - Compressed kernel image (arch/sh/boot/zImage)
> - adx_defconfig - Build for adx
> - cqreek_defconfig - Build for cqreek
> - dreamcast_defconfig - Build for dreamcast
> -...
> - vapor_defconfig - Build for vapor
> +
> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
> + - adx_defconfig - Build for adx
> + - cqreek_defconfig - Build for cqreek
> + - dreamcast_defconfig - Build for dreamcast
> + - ...
> + - vapor_defconfig - Build for vapor
>
> which then allows you to do:
>
> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
> similarity index 90%
> rename from Documentation/sh/register-banks.txt
> rename to Documentation/sh/register-banks.rst
> index a6719f2f6594..acccfaf80355 100644
> --- a/Documentation/sh/register-banks.txt
> +++ b/Documentation/sh/register-banks.rst
> @@ -1,8 +1,9 @@
> - Notes on register bank usage in the kernel
> - ==========================================
> +==========================================
> +Notes on register bank usage in the kernel
> +==========================================
>
> Introduction
> -------------
> +============
>
> The SH-3 and SH-4 CPU families traditionally include a single partial register
> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
> - The SR.IMASK interrupt handler makes use of this to set the
> interrupt priority level (used by local_irq_enable())
> - r7_bank (current)
> -
> --
> 2.17.1
>
Thanks,
Mauro
^ permalink raw reply
* [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Vandana BN @ 2019-06-29 14:32 UTC (permalink / raw)
To: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, mchehab
Cc: skhan, gregkh, linux-kernel-mentees, Vandana BN
In-Reply-To: <20190627063347.11137-1-bnvandana@gmail.com>
This patch converts new-machine.txt and register-banks.txt
to ReST format, No content change.
Added interfaces.rst to contain kernel-doc markups from index.rst
Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
Added SPDX tag in index.rst
Signed-off-by: Vandana BN <bnvandana@gmail.com>
---
Documentation/sh/index.rst | 65 +------
Documentation/sh/interface.rst | 59 ++++++
.../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
...{register-banks.txt => register-banks.rst} | 8 +-
4 files changed, 163 insertions(+), 140 deletions(-)
create mode 100644 Documentation/sh/interface.rst
rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
index bc8db7ba894a..fec3c405b6b9 100644
--- a/Documentation/sh/index.rst
+++ b/Documentation/sh/index.rst
@@ -1,59 +1,14 @@
-=======================
-SuperH Interfaces Guide
-=======================
+.. SPDX-License-Identifier: GPL-2.0
-:Author: Paul Mundt
-
-Memory Management
-=================
-
-SH-4
-----
-
-Store Queue API
-~~~~~~~~~~~~~~~
-
-.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
- :export:
-
-SH-5
-----
-
-TLB Interfaces
-~~~~~~~~~~~~~~
-
-.. kernel-doc:: arch/sh/mm/tlb-sh5.c
- :internal:
-
-.. kernel-doc:: arch/sh/include/asm/tlb_64.h
- :internal:
+====================
+SuperH Documentation
+====================
-Machine Specific Interfaces
-===========================
-
-mach-dreamcast
---------------
-
-.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
- :internal:
-
-mach-x3proto
-------------
-
-.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
- :export:
-
-Busses
-======
-
-SuperHyway
-----------
-
-.. kernel-doc:: drivers/sh/superhyway/superhyway.c
- :export:
+:Author: Paul Mundt
-Maple
------
+.. toctree::
+ :maxdepth: 2
-.. kernel-doc:: drivers/sh/maple/maple.c
- :export:
+ interface
+ new-machine
+ register-banks
diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
new file mode 100644
index 000000000000..bc8db7ba894a
--- /dev/null
+++ b/Documentation/sh/interface.rst
@@ -0,0 +1,59 @@
+=======================
+SuperH Interfaces Guide
+=======================
+
+:Author: Paul Mundt
+
+Memory Management
+=================
+
+SH-4
+----
+
+Store Queue API
+~~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+ :export:
+
+SH-5
+----
+
+TLB Interfaces
+~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/mm/tlb-sh5.c
+ :internal:
+
+.. kernel-doc:: arch/sh/include/asm/tlb_64.h
+ :internal:
+
+Machine Specific Interfaces
+===========================
+
+mach-dreamcast
+--------------
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+ :internal:
+
+mach-x3proto
+------------
+
+.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
+ :export:
+
+Busses
+======
+
+SuperHyway
+----------
+
+.. kernel-doc:: drivers/sh/superhyway/superhyway.c
+ :export:
+
+Maple
+-----
+
+.. kernel-doc:: drivers/sh/maple/maple.c
+ :export:
diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
similarity index 79%
rename from Documentation/sh/new-machine.txt
rename to Documentation/sh/new-machine.rst
index e0961a66130b..b16c33342642 100644
--- a/Documentation/sh/new-machine.txt
+++ b/Documentation/sh/new-machine.rst
@@ -1,8 +1,8 @@
+================================
+Adding a new board to LinuxSH
+================================
- Adding a new board to LinuxSH
- ================================
-
- Paul Mundt <lethal@linux-sh.org>
+Paul Mundt <lethal@linux-sh.org>
This document attempts to outline what steps are necessary to add support
for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
@@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
companion chip type, and CPU type. Looking at a tree view of this directory
hierarchy looks like the following:
-Board-specific code:
-
-.
-|-- arch
-| `-- sh
-| `-- boards
-| |-- adx
-| | `-- board-specific files
-| |-- bigsur
-| | `-- board-specific files
-| |
-| ... more boards here ...
-|
-`-- include
- `-- asm-sh
- |-- adx
- | `-- board-specific headers
- |-- bigsur
- | `-- board-specific headers
- |
- .. more boards here ...
-
-Next, for companion chips:
-.
-`-- arch
- `-- sh
- `-- cchips
- `-- hd6446x
- `-- hd64461
- `-- cchip-specific files
+Board-specific code::
+
+ .
+ |-- arch
+ | `-- sh
+ | `-- boards
+ | |-- adx
+ | | `-- board-specific files
+ | |-- bigsur
+ | | `-- board-specific files
+ | |
+ | ... more boards here ...
+ |
+ `-- include
+ `-- asm-sh
+ |-- adx
+ | `-- board-specific headers
+ |-- bigsur
+ | `-- board-specific headers
+ |
+ .. more boards here ...
+
+Next, for companion chips::
+
+ .
+ `-- arch
+ `-- sh
+ `-- cchips
+ `-- hd6446x
+ `-- hd64461
+ `-- cchip-specific files
... and so on. Headers for the companion chips are treated the same way as
board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
hd64461-specific headers.
-Finally, CPU family support is also abstracted:
-.
-|-- arch
-| `-- sh
-| |-- kernel
-| | `-- cpu
-| | |-- sh2
-| | | `-- SH-2 generic files
-| | |-- sh3
-| | | `-- SH-3 generic files
-| | `-- sh4
-| | `-- SH-4 generic files
-| `-- mm
-| `-- This is also broken out per CPU family, so each family can
-| have their own set of cache/tlb functions.
-|
-`-- include
- `-- asm-sh
- |-- cpu-sh2
- | `-- SH-2 specific headers
- |-- cpu-sh3
- | `-- SH-3 specific headers
- `-- cpu-sh4
- `-- SH-4 specific headers
+Finally, CPU family support is also abstracted::
+
+ .
+ |-- arch
+ | `-- sh
+ | |-- kernel
+ | | `-- cpu
+ | | |-- sh2
+ | | | `-- SH-2 generic files
+ | | |-- sh3
+ | | | `-- SH-3 generic files
+ | | `-- sh4
+ | | `-- SH-4 generic files
+ | `-- mm
+ | `-- This is also broken out per CPU family, so each family can
+ | have their own set of cache/tlb functions.
+ |
+ `-- include
+ `-- asm-sh
+ |-- cpu-sh2
+ | `-- SH-2 specific headers
+ |-- cpu-sh3
+ | `-- SH-3 specific headers
+ `-- cpu-sh4
+ `-- SH-4 specific headers
It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
need to be dealt with by the CPU family specific code.
@@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
get_system_type() and platform_setup(). For our imaginary board, this
might look something like:
-/*
- * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
- */
-#include <linux/init.h>
+.. code-block:: c
+
+ /*
+ * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
+ */
+ #include <linux/init.h>
-const char *get_system_type(void)
-{
- return "FooTech Vaporboard";
-}
+ const char *get_system_type(void)
+ {
+ return "FooTech Vaporboard";
+ }
-int __init platform_setup(void)
-{
+ int __init platform_setup(void)
+ {
/*
* If our hardware actually existed, we would do real
* setup here. Though it's also sane to leave this empty
@@ -136,7 +140,8 @@ int __init platform_setup(void)
/* And whatever else ... */
return 0;
-}
+ }
+
Our new imaginary board will also have to tie into the machvec in order for it
to be of any use.
@@ -172,16 +177,17 @@ sufficient.
vector.
Note that these prototypes are generated automatically by setting
- __IO_PREFIX to something sensible. A typical example would be:
+ __IO_PREFIX to something sensible. A typical example would be::
#define __IO_PREFIX vapor
#include <asm/io_generic.h>
+
somewhere in the board-specific header. Any boards being ported that still
have a legacy io.h should remove it entirely and switch to the new model.
- Add machine vector definitions to the board's setup.c. At a bare minimum,
- this must be defined as something like:
+ this must be defined as something like::
struct sh_machine_vector mv_vapor __initmv = {
.mv_name = "vapor",
@@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
require the proper entry here and there in order to get things done.
The first thing to do is to add an entry to arch/sh/Kconfig, under the
-"System type" menu:
+"System type" menu::
-config SH_VAPOR
- bool "Vapor"
- help
+ config SH_VAPOR
+ bool "Vapor"
+ help
select Vapor if configuring for a FooTech Vaporboard.
next, this has to be added into arch/sh/Makefile. All boards require a
@@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
implicit checks for your board if you need this somewhere throughout the
common code, such as:
+::
+
/* Make sure we're on the FooTech Vaporboard */
if (!mach_is_vapor())
return -ENODEV;
@@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
Looking at the 'make help' output, you should now see something like:
Architecture specific targets (sh):
- zImage - Compressed kernel image (arch/sh/boot/zImage)
- adx_defconfig - Build for adx
- cqreek_defconfig - Build for cqreek
- dreamcast_defconfig - Build for dreamcast
-...
- vapor_defconfig - Build for vapor
+
+ - zImage - Compressed kernel image (arch/sh/boot/zImage)
+ - adx_defconfig - Build for adx
+ - cqreek_defconfig - Build for cqreek
+ - dreamcast_defconfig - Build for dreamcast
+ - ...
+ - vapor_defconfig - Build for vapor
which then allows you to do:
diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
similarity index 90%
rename from Documentation/sh/register-banks.txt
rename to Documentation/sh/register-banks.rst
index a6719f2f6594..acccfaf80355 100644
--- a/Documentation/sh/register-banks.txt
+++ b/Documentation/sh/register-banks.rst
@@ -1,8 +1,9 @@
- Notes on register bank usage in the kernel
- ==========================================
+==========================================
+Notes on register bank usage in the kernel
+==========================================
Introduction
-------------
+============
The SH-3 and SH-4 CPU families traditionally include a single partial register
bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
@@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
- The SR.IMASK interrupt handler makes use of this to set the
interrupt priority level (used by local_irq_enable())
- r7_bank (current)
-
--
2.17.1
^ permalink raw reply related
* Re: [PATCH 00/10] Intel(R) Speed Select Technology
From: Andy Shevchenko @ 2019-06-29 14:29 UTC (permalink / raw)
To: Srinivas Pandruvada
Cc: Darren Hart, Andy Shevchenko, Andriy Shevchenko, Jonathan Corbet,
Rafael J. Wysocki, Alan Cox, Len Brown, prarit, darcari,
Linux Documentation List, Linux Kernel Mailing List,
Platform Driver
In-Reply-To: <20190626223851.19138-1-srinivas.pandruvada@linux.intel.com>
On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
>
> Intel® Speed Select Technology (Intel® SST) — A powerful new collection of
> features giving more granular control over CPU performance for optimized total
> cost of ownership and performance. With Intel® SST, one server can be configured
> for power and performance for variety of diverse workload requirements. In the
> Linux submission code. we are using ISST to specify Intel® SST to avoid confusion
> with existing use of SST for "Smart Sound Technology".
>
> Refer to these links for overview of the technology released with some Intel® Xeon®
> Scalable processor (5218N, 6230N, and 6252N):
> https://www.intel.com/content/www/us/en/architecture-and-technology/speed-select-technology-article.html
> https://builders.intel.com/docs/networkbuilders/intel-speed-select-technology-base-frequency-enhancing-performance.pdf
>
> The next generation of Intel® Xeon® processors are adding more features to the
> Intel® Speed Select Technology and allow dynamic configuration of these features
> from OS-software level instead from BIOS. This submission is adding new features
> and dynamic configuration capabilities .
>
>
> Intel SST Features:
>
> Intel® SST—Performance Profile (PP or perf-profile):
> This feature allows one server to be configured for different workload requirements
> instead of deploying different servers based on the workload requirement reducing total
> cost of ownership. With a single server deployed, the same server can be reconfigured
> dynamically to one of the supported profiles to suit the specific workload requirements.
> This feature introduces a mechanism that allows multiple optimized performance profiles
> per system via static and/or dynamic adjustment of TDP level and other performance
> parameters.
>
> Intel® SST—Core power (CP or core-power):
> An Interface that allows user to define per core priority. This defines a mechanism
> to distribute power among cores when there is a power constrained scenario. This defines
> a class of service configuration. Each CPU core can be tied to a class of service and hence
> an associated priority.
>
> Intel® SST—Base Frequency (BF or base-freq):
> The Intel® SST-BF feature lets user control and direct base frequency. If some critical
> workload threads demand constant high guaranteed performance, then this feature can be
> used to execute the thread at higher base frequency on specific set of CPUs.
>
> Intel® SST—Turbo frequency (TF or turbo-freq):
> Enables the ability to set different all core turbo ratio limits to cores based on the priority.
> Using this features some cores can be configured to get higher turbo frequency by designating
> them as high priority at the cost of lower or no turbo frequency on the low priority cores.
>
> Implementation
>
> The Intel® SST features are implemented in the firmware executing in the the power
> management unit (we are calling PUNIT here for short). The mechanism to control these
> features are specific to firmware implementation for Intel® Xeon® CPUs and are not architectural
> features. The interface mechanism and semantics of the messages can change in future Xeon
> CPUs. Hence there is minimal kernel implementation by offering direct communication
> to PUNIT via set of IOCTLs. The actual messages which can be sent to PUNIT are specified
> in the following document link:
>
> https://github.com/intel/CommsPowerManagement/blob/master/intel_sst_os_interface/mailbox.md
>
> The idea here is that user space software like cloud orchestration software based on their workload
> requirement configure the system. There is a full featured "Intel Speed Select" utility
> submitted to kernel power tools, which can be used to validate and exercise the features.
>
> Types of PUNIT interfaces
> There are two types of interfaces. One using Mail box communications, which is facilitated
> by a PCI device or in some Xeon® CPUs using MSRs; and other using an MMIO interface, which is
> used primarily for core prioritization. For hiding details a single character device is created
> to handle IOCTLs. The following block diagram shows the implementation overview.
>
>
> User User Space tool(intel-speed-select)/Cloud Orchestration software
> IOCTLs
> ---------------------------------------character device------------------------------
> kernel Common driver handling IOCTLs
> Mail Box drivers(PCI & MSR) PCI MMIO driver
> --------------------------------------------------------------------------
> Hardware PUNIT
>
>
>
Pushed to my review and testing queue, thanks!
> Srinivas Pandruvada (10):
> platform/x86: ISST: Update ioctl-number.txt for Intel Speed Select
> interface
> platform/x86: ISST: Add common API to register and handle ioctls
> platform/x86: ISST: Store per CPU information
> platform/x86: ISST: Add IOCTL to Translate Linux logical CPU to PUNIT
> CPU number
> platform/x86: ISST: Add Intel Speed Select mmio interface
> platform/x86: ISST: Add Intel Speed Select mailbox interface via PCI
> platform/x86: ISST: Add Intel Speed Select mailbox interface via MSRs
> platform/x86: ISST: Add Intel Speed Select PUNIT MSR interface
> platform/x86: ISST: Restore state on resume
> tools/power/x86: A tool to validate Intel Speed Select commands
>
> Documentation/ioctl/ioctl-number.txt | 1 +
> drivers/platform/x86/Kconfig | 2 +
> drivers/platform/x86/Makefile | 1 +
> .../x86/intel_speed_select_if/Kconfig | 17 +
> .../x86/intel_speed_select_if/Makefile | 10 +
> .../intel_speed_select_if/isst_if_common.c | 672 +++++++
> .../intel_speed_select_if/isst_if_common.h | 69 +
> .../intel_speed_select_if/isst_if_mbox_msr.c | 216 +++
> .../intel_speed_select_if/isst_if_mbox_pci.c | 214 +++
> .../x86/intel_speed_select_if/isst_if_mmio.c | 180 ++
> include/uapi/linux/isst_if.h | 172 ++
> tools/power/x86/intel_speed_select/Makefile | 31 +
> tools/power/x86/intel_speed_select/isst.h | 231 +++
> .../x86/intel_speed_select/isst_config.c | 1607 +++++++++++++++++
> .../power/x86/intel_speed_select/isst_core.c | 721 ++++++++
> .../x86/intel_speed_select/isst_display.c | 479 +++++
> 16 files changed, 4623 insertions(+)
> create mode 100644 drivers/platform/x86/intel_speed_select_if/Kconfig
> create mode 100644 drivers/platform/x86/intel_speed_select_if/Makefile
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_common.c
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_common.h
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_mbox_msr.c
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_mbox_pci.c
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_mmio.c
> create mode 100644 include/uapi/linux/isst_if.h
> create mode 100644 tools/power/x86/intel_speed_select/Makefile
> create mode 100644 tools/power/x86/intel_speed_select/isst.h
> create mode 100644 tools/power/x86/intel_speed_select/isst_config.c
> create mode 100644 tools/power/x86/intel_speed_select/isst_core.c
> create mode 100644 tools/power/x86/intel_speed_select/isst_display.c
>
> --
> 2.17.2
>
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Wolfram Sang @ 2019-06-29 10:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Rudolf Marek,
Seth Heasley, Neil Horman, Vadim Pasternak, Michael Shych,
Ajay Gupta, Peter Korsgaard, Andrew Lunn, Jim Cromie, Mark Brown,
Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, Alessandro Zummo, Alexandre Belloni,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <3997b54a2e73887b96ec665573f08ded78b71421.1561756511.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 595 bytes --]
On Fri, Jun 28, 2019 at 06:23:14PM -0300, Mauro Carvalho Chehab wrote:
> Convert each file at I2C subsystem, renaming them to .rst and
> adding to the driver-api book.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
I glimpsed over it and it looks basically OK. I won't have time to
actually review all of this. But I trust you and we can fix things
later. So:
Acked-by: Wolfram Sang <wsa@the-dreams.de>
I assume this goes in via your or doc-tree?
> Next/merge.log | 6 +-
This file doesn't exist upstream, though.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* Re: [PATCH] docs: packing: move it to core-api book and adjust markups
From: Mike Rapoport @ 2019-06-29 10:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vladimir Oltean, Mike Rapoport, Andrew Morton,
Randy Dunlap, Matthew Wilcox, Kent Overstreet, Arnd Bergmann,
Jonathan Neuschäfer, David S. Miller, netdev
In-Reply-To: <46cb79dbc4bbff3e5a4e77b548df1e92c105ed0f.1561804613.git.mchehab+samsung@kernel.org>
On Sat, Jun 29, 2019 at 07:37:02AM -0300, Mauro Carvalho Chehab wrote:
> The packing.txt file was misplaced, as docs should be part of
> a documentation book, and not at the root dir.
>
> So, move it to the core-api directory and add to its index.
>
> Also, ensure that the file will be properly parsed and the bitmap
> ascii artwork will use a monotonic font.
>
> Fixes: 554aae35007e ("lib: Add support for generic packing operations")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> Documentation/core-api/index.rst | 1 +
> .../{packing.txt => core-api/packing.rst} | 81 +++++++++++--------
> 2 files changed, 50 insertions(+), 32 deletions(-)
> rename Documentation/{packing.txt => core-api/packing.rst} (61%)
>
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index d1e5b95bf86d..aebb16d7771f 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -25,6 +25,7 @@ Core utilities
> librs
> genalloc
> errseq
> + packing
> printk-formats
> circular-buffers
> generic-radix-tree
> diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
> similarity index 61%
> rename from Documentation/packing.txt
> rename to Documentation/core-api/packing.rst
> index f830c98645f1..d8c341fe383e 100644
> --- a/Documentation/packing.txt
> +++ b/Documentation/core-api/packing.rst
> @@ -30,6 +30,7 @@ The solution
> ------------
>
> This API deals with 2 basic operations:
> +
> - Packing a CPU-usable number into a memory buffer (with hardware
> constraints/quirks)
> - Unpacking a memory buffer (which has hardware constraints/quirks)
> @@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
>
> 1. Normally (no quirks), we would do it like this:
>
> -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> -7 6 5 4
> -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> -3 2 1 0
> +::
> +
> + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> + 7 6 5 4
> + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> + 3 2 1 0
>
> That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
> LSByte (0) of the u64 sits at memory offset 7.
> @@ -63,10 +66,12 @@ comments as "logical" notation.
>
> 2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
>
> -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> -7 6 5 4
> -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> -3 2 1 0
> +::
> +
> + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> + 7 6 5 4
> + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> + 3 2 1 0
>
> That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
> inverts bit offsets inside a byte.
> @@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
>
> 3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
>
> -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> -4 5 6 7
> -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> -0 1 2 3
> +::
> +
> + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> + 4 5 6 7
> + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> + 0 1 2 3
>
> Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
> byte from each 4-byte word is placed at its mirrored position compared to
> @@ -86,18 +93,22 @@ the boundary of that word.
> 4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
> like this:
>
> -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> -4 5 6 7
> -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> -0 1 2 3
> +::
> +
> + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> + 4 5 6 7
> + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> + 0 1 2 3
>
>
> 5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
>
> -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> -3 2 1 0
> -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> -7 6 5 4
> +::
> +
> + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> + 3 2 1 0
> + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> + 7 6 5 4
>
> In this case the 8 byte memory region is interpreted as follows: first
> 4 bytes correspond to the least significant 4-byte word, next 4 bytes to
> @@ -107,28 +118,34 @@ the more significant 4-byte word.
> 6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
> this:
>
> -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> -3 2 1 0
> -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> -7 6 5 4
> +::
> +
> + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> + 3 2 1 0
> + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> + 7 6 5 4
>
>
> 7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
> this:
>
> -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> -0 1 2 3
> -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> -4 5 6 7
> +::
> +
> + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> + 0 1 2 3
> + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> + 4 5 6 7
>
>
> 8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
> are set, it looks like this:
>
> -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> -0 1 2 3
> -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> -4 5 6 7
> +::
> +
> + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> + 0 1 2 3
> + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> + 4 5 6 7
>
>
> We always think of our offsets as if there were no quirk, and we translate
> --
> 2.21.0
>
--
Sincerely yours,
Mike.
^ permalink raw reply
* [PATCH] docs: packing: move it to core-api book and adjust markups
From: Mauro Carvalho Chehab @ 2019-06-29 10:37 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vladimir Oltean, Mike Rapoport, Andrew Morton,
Randy Dunlap, Matthew Wilcox, Kent Overstreet, Arnd Bergmann,
Jonathan Neuschäfer, David S. Miller, netdev
The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.
So, move it to the core-api directory and add to its index.
Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.
Fixes: 554aae35007e ("lib: Add support for generic packing operations")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/core-api/index.rst | 1 +
.../{packing.txt => core-api/packing.rst} | 81 +++++++++++--------
2 files changed, 50 insertions(+), 32 deletions(-)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d1e5b95bf86d..aebb16d7771f 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@ Core utilities
librs
genalloc
errseq
+ packing
printk-formats
circular-buffers
generic-radix-tree
diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
similarity index 61%
rename from Documentation/packing.txt
rename to Documentation/core-api/packing.rst
index f830c98645f1..d8c341fe383e 100644
--- a/Documentation/packing.txt
+++ b/Documentation/core-api/packing.rst
@@ -30,6 +30,7 @@ The solution
------------
This API deals with 2 basic operations:
+
- Packing a CPU-usable number into a memory buffer (with hardware
constraints/quirks)
- Unpacking a memory buffer (which has hardware constraints/quirks)
@@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
1. Normally (no quirks), we would do it like this:
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
+::
+
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
LSByte (0) of the u64 sits at memory offset 7.
@@ -63,10 +66,12 @@ comments as "logical" notation.
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
+::
+
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
inverts bit offsets inside a byte.
@@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
+::
+
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
byte from each 4-byte word is placed at its mirrored position compared to
@@ -86,18 +93,22 @@ the boundary of that word.
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
like this:
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
+::
+
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
+::
+
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
In this case the 8 byte memory region is interpreted as follows: first
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@@ -107,28 +118,34 @@ the more significant 4-byte word.
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
this:
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
+::
+
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
this:
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
+::
+
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
are set, it looks like this:
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
+::
+
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
We always think of our offsets as if there were no quirk, and we translate
--
2.21.0
^ permalink raw reply related
* [PATCH] docs: ipmb: place it at driver-api and convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-29 10:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Greg Kroah-Hartman, Randy Dunlap,
Rafael J. Wysocki, Logan Gunthorpe, Asmaa Mnebhi, Corey Minyard,
vadimp
No new doc should be added at the main Documentation/ directory.
Instead, new docs should be added as ReST files, within the
Kernel documentation body.
Fixes: 51bd6f291583 ("Add support for IPMB driver")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
.../{IPMB.txt => driver-api/ipmb.rst} | 62 ++++++++++---------
2 files changed, 33 insertions(+), 30 deletions(-)
rename Documentation/{IPMB.txt => driver-api/ipmb.rst} (71%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index e33849b948c7..e49c34bf16c0 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -75,6 +75,7 @@ available subsections can be seen below.
dell_rbu
edid
eisa
+ ipmb
isa
isapnp
generic-counter
diff --git a/Documentation/IPMB.txt b/Documentation/driver-api/ipmb.rst
similarity index 71%
rename from Documentation/IPMB.txt
rename to Documentation/driver-api/ipmb.rst
index cd20c9764705..3ec3baed84c4 100644
--- a/Documentation/IPMB.txt
+++ b/Documentation/driver-api/ipmb.rst
@@ -32,11 +32,11 @@ This driver works with the I2C driver and a userspace
program such as OpenIPMI:
1) It is an I2C slave backend driver. So, it defines a callback
-function to set the Satellite MC as an I2C slave.
-This callback function handles the received IPMI requests.
+ function to set the Satellite MC as an I2C slave.
+ This callback function handles the received IPMI requests.
2) It defines the read and write functions to enable a user
-space program (such as OpenIPMI) to communicate with the kernel.
+ space program (such as OpenIPMI) to communicate with the kernel.
Load the IPMB driver
@@ -48,34 +48,35 @@ CONFIG_IPMB_DEVICE_INTERFACE=y
1) If you want the driver to be loaded at boot time:
-a) Add this entry to your ACPI table, under the appropriate SMBus:
+a) Add this entry to your ACPI table, under the appropriate SMBus::
-Device (SMB0) // Example SMBus host controller
-{
- Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
- Name (_UID, 0) // Unique ID of particular host controller
- :
- :
- Device (IPMB)
- {
- Name (_HID, "IPMB0001") // IPMB device interface
- Name (_UID, 0) // Unique device identifier
- }
-}
+ Device (SMB0) // Example SMBus host controller
+ {
+ Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
+ Name (_UID, 0) // Unique ID of particular host controller
+ :
+ :
+ Device (IPMB)
+ {
+ Name (_HID, "IPMB0001") // IPMB device interface
+ Name (_UID, 0) // Unique device identifier
+ }
+ }
-b) Example for device tree:
+b) Example for device tree::
-&i2c2 {
- status = "okay";
+ &i2c2 {
+ status = "okay";
- ipmb@10 {
- compatible = "ipmb-dev";
- reg = <0x10>;
- };
-};
+ ipmb@10 {
+ compatible = "ipmb-dev";
+ reg = <0x10>;
+ };
+ };
-2) Manually from Linux:
-modprobe ipmb-dev-int
+2) Manually from Linux::
+
+ modprobe ipmb-dev-int
Instantiate the device
@@ -86,15 +87,16 @@ described in 'Documentation/i2c/instantiating-devices.rst'.
If you have multiple BMCs, each connected to your Satellite MC via
a different I2C bus, you can instantiate a device for each of
those BMCs.
+
The name of the instantiated device contains the I2C bus number
-associated with it as follows:
+associated with it as follows::
-BMC1 ------ IPMB/I2C bus 1 ---------| /dev/ipmb-1
+ BMC1 ------ IPMB/I2C bus 1 ---------| /dev/ipmb-1
Satellite MC
-BMC1 ------ IPMB/I2C bus 2 ---------| /dev/ipmb-2
+ BMC1 ------ IPMB/I2C bus 2 ---------| /dev/ipmb-2
For instance, you can instantiate the ipmb-dev-int device from
-user space at the 7 bit address 0x10 on bus 2:
+user space at the 7 bit address 0x10 on bus 2::
# echo ipmb-dev 0x1010 > /sys/bus/i2c/devices/i2c-2/new_device
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Matthew Wilcox @ 2019-06-29 1:41 UTC (permalink / raw)
To: Sheriff Esseson
Cc: skhan, corbet, linux-doc, linux-kernel, linux-xfs,
linux-kernel-mentees
In-Reply-To: <20190629010733.GA31770@localhost>
On Sat, Jun 29, 2019 at 02:25:08AM +0100, Sheriff Esseson wrote:
> On Fri, Jun 28, 2019 at 10:43:24PM +0100, Sheriff Esseson wrote:
> > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > Documentation/index.rst.
Don't quote the entire previous patch when submitting a new one.
> Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
>
> CC xfs-list.
>
> Correct email indentation.
This text should be below the --- line, and it should be marked as "v2:"
And you didn't update the MAINTAINERS file.
> +For boolean mount options, the names with the "(*)" prefix is the
> +default behaviour. For example, take an behaviour enabled by default to be a one (1) or,
This line is too long. Doesn't checkpatch.pl complain?
> + 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.
Darrick mentioned the indentation was weird here, and you haven't fixed that.
> + 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
> + block units. This option is only relevant to filesystems
line length
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 1:25 UTC (permalink / raw)
To: skhan
Cc: skhan, corbet, linux-doc, linux-kernel, linux-xfs,
linux-kernel-mentees
In-Reply-To: <20190628214302.GA12096@localhost>
On Fri, Jun 28, 2019 at 10:43:24PM +0100, Sheriff Esseson wrote:
> Convert xfs.txt to ReST, markup and rename accordingly. Update
> Documentation/index.rst.
>
> 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@gmail.com>
> ---
> 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
> 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
> + 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
> + ``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.
> 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.
>
> 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.
> + In an XFS filesystem, the log section can be separate from
> + the data section or contained within it.
>
> - 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.
> +
> + 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
> + 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
> + block units. This option, like ``sunit`` above, is only
> + relevant to filesystems that were created with non-zero data alignment parameters.
> +
> + 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.
>
> fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
> --
> 2.22.0
>
Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
CC xfs-list.
Correct email indentation.
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
Documentation/filesystems/index.rst | 5 +-
.../filesystems/{xfs.txt => xfs.rst} | 193 ++++++++++--------
2 files changed, 107 insertions(+), 91 deletions(-)
rename Documentation/filesystems/{xfs.txt => xfs.rst} (73%)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
similarity index 73%
rename from Documentation/filesystems/xfs.txt
rename to Documentation/filesystems/xfs.rst
index a5cbb5e0e..a8357cbd3 100644
--- a/Documentation/filesystems/xfs.txt
+++ b/Documentation/filesystems/xfs.rst
@@ -1,4 +1,4 @@
-
+======================
The SGI XFS Filesystem
======================
@@ -18,10 +18,11 @@ Mount Options
=============
When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
+For boolean mount options, the names with the "(*)" prefix is the
+default behaviour. For example, take an behaviour enabled by default to be a one (1) or,
+a zero (0) otherwise, ``(*)[no]default`` would be 0 and ``[no](*)default`` a 1.
- 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 +35,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
+ 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
+ ``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.
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.
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.
+ In an XFS filesystem, the log section can be separate from
+ the data section or contained within it.
- 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.
+
+ 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
+ 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
+ block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment parameters.
+
+ 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 +317,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.
fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
--
2.22.0
^ permalink raw reply related
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Alexandre Belloni @ 2019-06-28 21:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <3997b54a2e73887b96ec665573f08ded78b71421.1561756511.git.mchehab+samsung@kernel.org>
On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> index 225a8df1d4e9..1803f3cab39f 100644
> --- a/drivers/rtc/rtc-ds1374.c
> +++ b/drivers/rtc/rtc-ds1374.c
> @@ -14,7 +14,7 @@
> */
> /*
> * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> - * recommened in .../Documentation/i2c/writing-clients section
> + * recommened in .../Documentation/i2c/writing-clients.rst section
> * "Sending and receiving", using SMBus level communication is preferred.
> */
>
Honestly, the whole comment could be removed. The current trend is to
move everything to regmap anyway.
However, I'm fine with that change if you want to keep it that way (and
probably scripted).
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply
* Re: [PATCH 1/5] docs: convert markdown documents to ReST
From: Rob Herring @ 2019-06-28 22:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel@vger.kernel.org, Jonathan Corbet, Mark Rutland,
devicetree
In-Reply-To: <7a5734d147788ffb817c8122dbb0ff619a718a71.1561756511.git.mchehab+samsung@kernel.org>
On Fri, Jun 28, 2019 at 3:23 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The documentation standard is ReST and not markdown.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/devicetree/writing-schema.md | 130 ---------------
> Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++
I wasn't really ever intending to integrate this into the rest of the
kernel docs, but I'm not tied to any format so:
Acked-by: Rob Herring <robh@kernel.org>
> ...entication.md => ubifs-authentication.rst} | 70 +++++---
> 3 files changed, 197 insertions(+), 156 deletions(-)
> delete mode 100644 Documentation/devicetree/writing-schema.md
> create mode 100644 Documentation/devicetree/writing-schema.rst
> rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Darrick J. Wong @ 2019-06-28 22:18 UTC (permalink / raw)
To: Matthew Wilcox
Cc: Sheriff Esseson, skhan, corbet, linux-doc, linux-kernel,
linux-xfs
In-Reply-To: <20190628215106.GE4286@bombadil.infradead.org>
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@gmail.com>
> > ---
> > 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
> >
^ permalink raw reply
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Alexandre Belloni @ 2019-06-28 22:10 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <20190628185445.71eb824b@coco.lan>
On 28/06/2019 18:54:45-0300, Mauro Carvalho Chehab wrote:
> Em Fri, 28 Jun 2019 23:41:38 +0200
> Alexandre Belloni <alexandre.belloni@bootlin.com> escreveu:
>
> > On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> > > diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> > > index 225a8df1d4e9..1803f3cab39f 100644
> > > --- a/drivers/rtc/rtc-ds1374.c
> > > +++ b/drivers/rtc/rtc-ds1374.c
> > > @@ -14,7 +14,7 @@
> > > */
> > > /*
> > > * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> > > - * recommened in .../Documentation/i2c/writing-clients section
> > > + * recommened in .../Documentation/i2c/writing-clients.rst section
> > > * "Sending and receiving", using SMBus level communication is preferred.
> > > */
> > >
> >
> > Honestly, the whole comment could be removed. The current trend is to
> > move everything to regmap anyway.
> >
> > However, I'm fine with that change if you want to keep it that way (and
> > probably scripted).
>
> While the conversion was manually made, the renames were scripted,
> and checked with:
>
> ./scripts/documentation-file-ref-check
>
> Otherwise I would very likely fix the typo:
>
> recommened -> recommended
>
> :-)
>
> I can certainly add new patch at this (before or after patch 3/5 - as you
> prefer) in order to get rid of the comment, but I would avoid doing a
> somewhat unrelated changes at the same documentation patch.
>
I'm okay with that.
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Mauro Carvalho Chehab @ 2019-06-28 21:54 UTC (permalink / raw)
To: Alexandre Belloni
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <20190628214138.GU3692@piout.net>
Em Fri, 28 Jun 2019 23:41:38 +0200
Alexandre Belloni <alexandre.belloni@bootlin.com> escreveu:
> On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> > diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> > index 225a8df1d4e9..1803f3cab39f 100644
> > --- a/drivers/rtc/rtc-ds1374.c
> > +++ b/drivers/rtc/rtc-ds1374.c
> > @@ -14,7 +14,7 @@
> > */
> > /*
> > * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> > - * recommened in .../Documentation/i2c/writing-clients section
> > + * recommened in .../Documentation/i2c/writing-clients.rst section
> > * "Sending and receiving", using SMBus level communication is preferred.
> > */
> >
>
> Honestly, the whole comment could be removed. The current trend is to
> move everything to regmap anyway.
>
> However, I'm fine with that change if you want to keep it that way (and
> probably scripted).
While the conversion was manually made, the renames were scripted,
and checked with:
./scripts/documentation-file-ref-check
Otherwise I would very likely fix the typo:
recommened -> recommended
:-)
I can certainly add new patch at this (before or after patch 3/5 - as you
prefer) in order to get rid of the comment, but I would avoid doing a
somewhat unrelated changes at the same documentation patch.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Shuah Khan @ 2019-06-28 21:53 UTC (permalink / raw)
To: Sheriff Esseson; +Cc: corbet, linux-doc, linux-kernel
In-Reply-To: <20190628214302.GA12096@localhost>
Hi Sheriff,
On 6/28/19 3:43 PM, Sheriff Esseson wrote:
> Convert xfs.txt to ReST, markup and rename accordingly. Update
> Documentation/index.rst.
>
> 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.
>
The commit log looks odd with these indentations.
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
> 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
> 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
> + 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
> + ``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.
> 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.
>
> 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.
> + In an XFS filesystem, the log section can be separate from
> + the data section or contained within it.
>
> - 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.
> +
> + 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
> + 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
> + block units. This option, like ``sunit`` above, is only
> + relevant to filesystems that were created with non-zero data alignment parameters.
> +
> + 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.
>
> fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
>
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Matthew Wilcox @ 2019-06-28 21:51 UTC (permalink / raw)
To: Sheriff Esseson
Cc: skhan, corbet, linux-doc, linux-kernel, linux-xfs,
Darrick J. Wong
In-Reply-To: <20190628214302.GA12096@localhost>
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?
You also need to update MAINTAINERS.
> 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@gmail.com>
> ---
> 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
> + 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
> + ``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.
> 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.
>
> 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.
> + In an XFS filesystem, the log section can be separate from
> + the data section or contained within it.
>
> - 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.
> +
> + 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
> + 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
> + block units. This option, like ``sunit`` above, is only
> + relevant to filesystems that were created with non-zero data alignment parameters.
> +
> + 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.
>
> fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
> --
> 2.22.0
>
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox