On Tue, Jul 02, 2019 at 01:30:40PM +0100, Sheriff Esseson wrote: > Convert xfs.txt to ReST, rename and fix broken references, consequently. > > Make the name "value" in "option=value" look like a variable (that it probably > is), by embedding in angle "<>" brackets, rather than something predifined > elsewhere. This is inline with the conventions in manuals. > > Also, make defaults of boolean options prefixed with "(*)". This is so that > options can be compressed to "[no]option" and on a single line, which renders > consistently and nicely in htmldocs. > > lastly, enforce a "one option, one definition" policy to keep things > consistent and simple. > > > Signed-off-by: Sheriff Esseson <sheriffesseson@xxxxxxxxx> > --- > > v5 aims to comply with the guiding comments on its previous versions. > > Documentation/filesystems/dax.txt | 2 +- > Documentation/filesystems/index.rst | 5 +- > Documentation/filesystems/xfs.rst | 468 +++++++++++++++++++++++++++ > Documentation/filesystems/xfs.txt | 470 ---------------------------- > MAINTAINERS | 2 +- > 5 files changed, 473 insertions(+), 474 deletions(-) > create mode 100644 Documentation/filesystems/xfs.rst > delete mode 100644 Documentation/filesystems/xfs.txt > > diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt > index 6d2c0d340..c333285b8 100644 > --- a/Documentation/filesystems/dax.txt > +++ b/Documentation/filesystems/dax.txt > @@ -76,7 +76,7 @@ exposure of uninitialized data through mmap. > These filesystems may be used for inspiration: > - ext2: see Documentation/filesystems/ext2.txt > - ext4: see Documentation/filesystems/ext4/ > -- xfs: see Documentation/filesystems/xfs.txt > +- xfs: see Documentation/filesystems/xfs.rst > > > Handling Media Errors > 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..d36ef042c > --- /dev/null > +++ b/Documentation/filesystems/xfs.rst > @@ -0,0 +1,468 @@ > +.. SPDX-License-Identifier: GPL-2.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 "(*)" 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. That's really confusing. Does this mean that I can pass discard=1 now? (no) I also don't really understand why we need to cram so much into a single line. Why not just: discard nodiscard (default) Something something discard chomps on free space, chomp chomp a chewy chomp, pretend I wrote the real text here, etc. Or if you really want the single-line header... [no]discard Something something discard chomps on free space, chomp chomp a chewy chomp, pretend I wrote the real text here, etc. ''nodiscard'' is the default setting. Please don't introduce '1's and '0's here because there are other parts of xfs where you /can/ enable or disable features by saying "foo=0" or "foo=1". There's probably more to say but the text reflowing since v1 makes this patch unreviewable because ugh 1000-line diff. --D > + > + 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@xxxxxxxxxxxxxxx > 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 >
