From d7be6ed15657ea572f0f3ad4962a052069b28310 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Thu, 18 Jan 2024 02:37:08 +0100 Subject: [PATCH] btrfs-progs: docs: mkfs and sectorsize updates [ci skip] Signed-off-by: David Sterba --- Documentation/Status.rst | 3 ++- Documentation/Subpage.rst | 18 ++++++++++-------- Documentation/mkfs.btrfs.rst | 11 ++++++++--- 3 files changed, 20 insertions(+), 12 deletions(-) diff --git a/Documentation/Status.rst b/Documentation/Status.rst index 5f682c66..987658c6 100644 --- a/Documentation/Status.rst +++ b/Documentation/Status.rst @@ -295,7 +295,8 @@ Subpage block size Most commonly used page sizes are 4KiB, 16KiB and 64KiB. All combinations with a 4KiB sector size filesystems are supported. Some features are not compatible -with subpage or require another feature to work: +with subpage or require another feature to work. Since btrfs-progs 6.7 the default +sector size is 4KiB as this allows cross-architecture compatibility. .. list-table:: :header-rows: 1 diff --git a/Documentation/Subpage.rst b/Documentation/Subpage.rst index 1655ae7e..4116f86e 100644 --- a/Documentation/Subpage.rst +++ b/Documentation/Subpage.rst @@ -6,22 +6,24 @@ using a filesystem that has different size of data block size (*sectorsize*) and the host CPU page size. For easier implementation the support was limited to the exactly same size of the block and page. On x86_64 this is typically 4KiB, but there are other architectures commonly used that make use of larger -pages, like 64KiB on 64bit ARM or PowerPC. This means filesystems created -with 64KiB sector size cannot be mounted on a system with 4KiB page size. +pages, like 64KiB on 64bit ARM or PowerPC or 16KiB on Apple Silicon. This means +filesystems created with 64KiB sector size cannot be mounted on a system with +4KiB page size. -Since v6.7, filesystems are created with a 4KiB sectorsize by default, -though it remains possible to create filesystems with other page sizes +Since btrfs-progs 6.7, filesystems are created with a 4KiB sector size by +default, though it remains possible to create filesystems with other sector sizes (such as 64KiB with the "-s 64k" option for :command:`mkfs.btrfs`). This -ensures that new filesystems are compatible across other architecture -variants using larger page sizes. +ensures that new filesystems are compatible across other architecture variants +using larger page sizes. Requirements, limitations ------------------------- -The initial subpage support has been added in v5.15. Most features are +The initial subpage support has been added in kernel 5.15. Most features are already working without problems. On a 64KiB page system, a filesystem with 4KiB sectorsize can be mounted and used as long as the initial mount succeeds. -Subpage support is used by default for systems with a non-4KiB page size since v6.7. +Subpage support is used by default for systems with a non-4KiB page size since +btrfs-progs 6.7. Please refer to status page of :ref:`status-subpage-block-size` for compatibility. diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst index be4f49cb..e725f3ce 100644 --- a/Documentation/mkfs.btrfs.rst +++ b/Documentation/mkfs.btrfs.rst @@ -122,15 +122,20 @@ OPTIONS -s|--sectorsize Specify the sectorsize, the minimum data block allocation unit. + .. note:: + Versions prior to 6.7 set the sectorsize matching the host CPU + page size, starting in 6.7 this is 4KiB for cross-architecture + compatibility. Please read more about the :doc:`subpage block size support` + and :ref:`its status`. + By default, the value is 4KiB, but it can be manually set to match the - system page size. However, if the sector size is different from the page + system page size (e.g. using command :command:`getconf PAGE_SIZE`). + However, if the sector size is different from the page size, the resulting filesystem may not be mountable by the current kernel, apart from the default 4KiB. Hence, using this option is not advised unless you intend to mount it on a system with the suitable page size. - .. note:: - Versions prior to 6.7 set the sectorsize matching to the page size. -L|--label Specify a label for the filesystem. The *string* should be less than 256