On Wed, Jul 10, 2013 at 07:03:59AM +1000, Dave Chinner wrote: > From: Dave Chinner <dchinner@xxxxxxxxxx> > > Because it's horribly out of date. > > And mark various deprecated options as deprecated and give them a > removal date. > > Signed-off-by: Dave Chinner <dchinner@xxxxxxxxxx> > Reviewed-by: Mark Tinguely <tinguely@xxxxxxx> > --- > Documentation/filesystems/xfs.txt | 317 +++++++++++++++++++++++++------------- > 1 file changed, 209 insertions(+), 108 deletions(-) > > diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt > index 83577f0..12525b1 100644 > --- a/Documentation/filesystems/xfs.txt > +++ b/Documentation/filesystems/xfs.txt > @@ -18,6 +18,8 @@ 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 > @@ -25,97 +27,128 @@ When mounting an XFS filesystem, the following options are accepted. > Valid values for this option are page size (typically 4KiB) > through to 1GiB, inclusive, in power-of-2 increments. > > - attr2/noattr2 > - The options enable/disable (default is disabled for backward > - compatibility on-disk) 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 (by 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 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. > > - barrier > - Enables the use of block layer write barriers for writes into > - the journal and unwritten extent conversion. This allows for > - drive level write caching to be enabled, for devices that > - support write barriers. > + barrier (*) > + nobarrier > + Enables/disables the use of block layer write barriers for > + writes into the journal and for data integrity operations. > + This allows for drive level write caching to be enabled, for > + devices that support write barriers. > > discard > - Issue command 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. > - > - dmapi > - Enable the DMAPI (Data Management API) event callouts. > - Use with the "mtpt" option. > - > - grpid/bsdgroups and 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 (the default) 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. > - > - ihashsize=value > - In memory inode hashes have been removed, so this option has > - no function as of August 2007. Option is deprecated. > - > - ikeep/noikeep > - When ikeep is specified, XFS does not delete empty inode clusters > - and keeps them around on disk. ikeep is the traditional XFS > - behaviour. When noikeep is specified, empty inode clusters > - are returned to the free space pool. The default is noikeep for > - non-DMAPI mounts, while ikeep is the default when DMAPI is in use. > - > - inode64 > - 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. This is > - the default allocation option. Applications which do not handle > - inode numbers bigger than 32 bits, should use inode32 option. > + 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 > - Indicates that XFS is limited to create inodes at locations which > - will not result in inode numbers with more than 32 bits of > - significance. This is provided for backwards compatibility, since > - 64 bits inode numbers might cause problems for some applications > - that cannot handle large inode numbers. > - > - largeio/nolargeio > + 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. > - If "largeio" specified, a filesystem that has 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. > - If neither of these two options are specified, then filesystem > - will behave as if "nolargeio" was specified. > + 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 for filesystems with a > - blocksize of 64KiB, 4 buffers for filesystems with a blocksize > - of 32KiB, 3 buffers for filesystems with a blocksize of 16KiB > - and 2 buffers for all other configurations. Increasing the > - number of buffers may increase performance on some workloads > - at the cost of the memory used for the additional log buffers > - and their associated control structures. > + 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 relevent to > + this case. > > logbsize=value > - Set the size of each in-memory log buffer. > - 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 default value for machines with more than 32MiB of memory > - is 32768, machines with less memory use 16384 by default. > + 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. > @@ -124,16 +157,11 @@ When mounting an XFS filesystem, the following options are accepted. > optional, and the log section can be separate from the data > section or contained within it. > > - mtpt=mountpoint > - Use with the "dmapi" option. The value specified here will be > - included in the DMAPI mount event, and should be the path of > - the actual mountpoint that is used. > - > noalign > - Data allocations will not be aligned at stripe unit boundaries. > - > - noatime > - Access timestamps are not updated when a file is read. > + 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. > @@ -144,8 +172,14 @@ When mounting an XFS filesystem, the following options are accepted. > 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. > + 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) > @@ -160,24 +194,64 @@ When mounting an XFS filesystem, the following options are accepted. > 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. > - If this option is not specified and the filesystem was made on > - a stripe volume or the stripe width or unit were specified for > - the RAID device at mkfs time, then the mount system call will > - restore the value from the superblock. For filesystems that > - are made directly on RAID devices, these options can be used > - to override the information in the superblock if the underlying > - disk layout changes after the filesystem has been created. > - The "swidth" option is required if the "sunit" option has been > - specified, and must be a multiple of the "sunit" 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 > +======================== > + > + delaylog/nodelaylog > + Delayed logging is the only logging method that XFS supports > + now, so these mount options are now ignored. > + > + Due for removal in 3.12. > + > + ihashsize=value > + In memory inode hashes have been removed, so this option has > + no function as of August 2007. Option is deprecated. > + > + Due for removal in 3.12. > + > + irixsgid > + This behaviour is now controlled by a sysctl, so the mount > + option is ignored. > + > + Due for removal in 3.12. > + > + osyncisdsync > + osyncisosync > + O_SYNC and O_DSYNC are fully supported, so there is no need > + for these options any more. > + > + Due for removal in 3.12. I finally read through Documentation/ABI/README, and I agree this all seems fairly reasonable with respect to that doc. I do agree that it would be good to add these into the Documentation/ABI/obsolete directory. The only other concern that I have is that the doc is saying that they want two years notice. 3.12 might be a little short for that timeframe. Anyway we can cross that bridge when we come to it. Applied. -Ben _______________________________________________ xfs mailing list xfs@xxxxxxxxxxx http://oss.sgi.com/mailman/listinfo/xfs
