On 2/22/21 9:01 PM, Darrick J. Wong wrote: > From: Darrick J. Wong <djwong@xxxxxxxxxx> > > Update the manual pages for the most popular tools to note which options > are only useful with the V4 XFS format, and that the V4 format is > deprecated and will be removed no later than September 2030. > > Signed-off-by: Darrick J. Wong <djwong@xxxxxxxxxx> > --- > man/man8/mkfs.xfs.8 | 16 ++++++++++++++++ > man/man8/xfs_admin.8 | 10 ++++++++++ > 2 files changed, 26 insertions(+) > > > diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8 > index fac82d74..df25abaa 100644 > --- a/man/man8/mkfs.xfs.8 > +++ b/man/man8/mkfs.xfs.8 > @@ -223,6 +223,11 @@ of calculating and checking the CRCs is not noticeable in normal operation. > By default, > .B mkfs.xfs > will enable metadata CRCs. > +.IP > +Formatting a filesystem without CRCs selects the V4 format, which is deprecated > +and will be removed from upstream in September 2030. Can I add: + Several other options, noted below, are only tunable on V4 formats, and will + be removed along with the V4 format itself. > +Distributors may choose to withdraw support for the V4 format earlier than > +this date. > .TP > .BI finobt= value > This option enables the use of a separate free inode btree index in each > @@ -592,6 +597,8 @@ This option can be used to turn off inode alignment when the > filesystem needs to be mountable by a version of IRIX > that does not have the inode alignment feature > (any release of IRIX before 6.2, and IRIX 6.2 without XFS patches). > +.IP > +This option only applies to the deprecated V4 format. and can I change this (and other mkfs option notes) to: + This option is only tunable on the deprecated V4 format. because we actually do accept i.e. "-i attr=2" on a V5 format today. so, "you can't tune it on v5, and it goes away when v4 does" seems to capture what you want the user to know. > .TP > .BI attr= value > This is used to specify the version of extended attribute inline > @@ -602,6 +609,8 @@ between attribute and extent data. > The previous version 1, which has fixed regions for attribute and > extent data, is kept for backwards compatibility with kernels older > than version 2.6.16. > +.IP > +This option only applies to the deprecated V4 format. > .TP > .BI projid32bit[= value ] > This is used to enable 32bit quota project identifiers. The > @@ -609,6 +618,8 @@ This is used to enable 32bit quota project identifiers. The > is either 0 or 1, with 1 signifying that 32bit projid are to be enabled. > If the value is omitted, 1 is assumed. (This default changed > in release version 3.2.0.) > +.IP > +This option only applies to the deprecated V4 format. > .TP > .BI sparse[= value ] > Enable sparse inode chunk allocation. The > @@ -690,6 +701,7 @@ stripe-aligned log writes (see the sunit and su options, below). > The previous version 1, which is limited to 32k log buffers and does > not support stripe-aligned writes, is kept for backwards compatibility > with very old 2.4 kernels. > +This option only applies to the deprecated V4 format. > .TP > .BI sunit= value > This specifies the alignment to be used for log writes. The > @@ -744,6 +756,8 @@ is 1 (on) so you must specify > .B lazy-count=0 > if you want to disable this feature for older kernels which don't support > it. > +.IP > +This option only applies to the deprecated V4 format. > .RE > .PP > .PD 0 > @@ -803,6 +817,8 @@ will be stored in the directory structure. The default value is 1. > When CRCs are enabled (the default), the ftype functionality is always > enabled, and cannot be turned off. > .IP > +This option only applies to the deprecated V4 format. > +.IP > .RE > .TP > .BI \-p " protofile" > diff --git a/man/man8/xfs_admin.8 b/man/man8/xfs_admin.8 > index cccbb224..5ef99316 100644 > --- a/man/man8/xfs_admin.8 > +++ b/man/man8/xfs_admin.8 > @@ -54,6 +54,8 @@ for a detailed description of the XFS log. > Enables unwritten extent support on a filesystem that does not > already have this enabled (for legacy filesystems, it can't be > disabled anymore at mkfs time). > +.IP > +This option only applies to the deprecated V4 format. > .TP > .B \-f > Specifies that the filesystem image to be processed is stored in a > @@ -67,12 +69,16 @@ option). > .B \-j > Enables version 2 log format (journal format supporting larger > log buffers). > +.IP > +This option only applies to the deprecated V4 format. > .TP > .B \-l > Print the current filesystem label. > .TP > .B \-p > Enable 32bit project identifier support (PROJID32BIT feature). > +.IP > +This option only applies to the deprecated V4 format. > .TP > .B \-u > Print the current filesystem UUID (Universally Unique IDentifier). > @@ -83,6 +89,8 @@ Enable (1) or disable (0) lazy-counters in the filesystem. > Lazy-counters may not be disabled on Version 5 superblock filesystems > (i.e. those with metadata CRCs enabled). > .IP > +In other words, this option only applies to the deprecated V4 format. > +.IP > This operation may take quite a bit of time on large filesystems as the > entire filesystem needs to be scanned when this option is changed. > .IP > @@ -92,6 +100,8 @@ information is kept in other parts of the filesystem to be able to > maintain the counter values without needing to keep them in the > superblock. This gives significant improvements in performance on some > configurations and metadata intensive workloads. > +.IP > +This option only applies to the deprecated V4 format. I think you're restated it here in the same section; I can just drop this extra one if you concur. > .TP > .BI \-L " label" > Set the filesystem label to >
