linux-xfs.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Eric Sandeen <sandeen@sandeen.net>
To: "Darrick J. Wong" <djwong@kernel.org>
Cc: linux-xfs@vger.kernel.org, hch@lst.de, bfoster@redhat.com
Subject: Re: [PATCH 1/5] man: mark all deprecated V4 format options
Date: Tue, 23 Feb 2021 18:26:05 -0600	[thread overview]
Message-ID: <14656568-caf9-c931-2387-e06f171d1ead@sandeen.net> (raw)
In-Reply-To: <161404929091.425731.465351236842105610.stgit@magnolia>

On 2/22/21 9:01 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <djwong@kernel.org>
> 
> 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@kernel.org>
> ---
>  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
> 

  reply	other threads:[~2021-02-24  1:30 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-02-23  3:01 [PATCHSET v6.1 0/5] xfs_admin: support upgrading v5 filesystems Darrick J. Wong
2021-02-23  3:01 ` [PATCH 1/5] man: mark all deprecated V4 format options Darrick J. Wong
2021-02-24  0:26   ` Eric Sandeen [this message]
2021-02-24  2:07     ` Darrick J. Wong
2021-02-23  3:01 ` [PATCH 2/5] xfs_repair: allow upgrades to v5 filesystems Darrick J. Wong
2021-02-23  3:01 ` [PATCH 3/5] xfs_admin: support adding features to V5 filesystems Darrick J. Wong
2021-02-23  3:01 ` [PATCH 4/5] xfs_repair: enable inobtcount upgrade via repair Darrick J. Wong
2021-02-23  3:01 ` [PATCH 5/5] xfs_repair: enable bigtime " Darrick J. Wong
  -- strict thread matches above, loose matches on Subject: below --
2021-02-13  5:47 [PATCHSET v6 0/5] xfs_admin: support upgrading v5 filesystems Darrick J. Wong
2021-02-13  5:47 ` [PATCH 1/5] man: mark all deprecated V4 format options Darrick J. Wong
2021-02-25  7:39   ` Christoph Hellwig

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=14656568-caf9-c931-2387-e06f171d1ead@sandeen.net \
    --to=sandeen@sandeen.net \
    --cc=bfoster@redhat.com \
    --cc=djwong@kernel.org \
    --cc=hch@lst.de \
    --cc=linux-xfs@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).