@@ -6,6 +6,59 @@ 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. A filesystem created on one cannot
-be mounted on the other. The subpage support is still work in progress in 5.18
-but the support is incrementally added with each release.
+pages, like 64KiB on 64bit ARM or PowerPC. This means filesystems created
+with 64KiB sector size can not be mounted on system with 4KiB page size.
+
+While with subpage support, systems with 64KiB page size can create (still needs
+"-s 4k" option for mkfs.btrfs) and mount filesystems with 4KiB sectorsize,
+allowing us to push 4KiB sectorsize as default sectorsize for all platforms in the
+near-future.
+
+
+Requirements, limitations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The subpage support is initially added in v5.15, although it's still
+considered as experimental at the time of writing (v5.18), most features are
+already working without problems.
+
+End users can mount filesystems with 4KiB sectorsize and do their usual
+workload, while should not notice any obvious change, as long as the initial
+mount succeeded (there are cases btrfs will reject the subpage mount though).
+
+The following features has some limitations for subpage:
+
+- RAID56 support
+ This support is already queued for v5.19 cycle.
+ Any fs with RAID56 chunks will be rejected at mount time for now.
+
+- Support for page size other than 64KiB
+ The support for other page sizes (16KiB, 32KiB and more) are already queued
+ for v5.19 cycle.
+ Initially the subpage support is only for 64KiB support, but the design makes
+ it pretty easy to enable support for other page sizes.
+
+- No inline extent creation
+ This is an artificial limit, to prevent mixed inline and regular extents.
+
+ It's possible to create mixed inline and regular extents even with
+ non-subpage mount for certain corner cases, it's way easier to create such
+ mixed extents for subpage.
+
+ Thus max_inline mount option will be sliently ignored for subpage mounts,
+ and it always acts as "max_inline=0".
+
+- Compression write is limited to page aligned ranges
+ Compression write for subpage is introduced in v5.16, with the limitation
+ that only page aligned range can be compressed.
+ This limitation is due to how btrfs handles delayed allocation.
+
+- No support for v1 space cache
+ V1 space cache is considered deprecated, and we're defaulting to v2 cache
+ in btrfs-progs already.
+ The old v1 cache has quite some hard coded page size usage, and consider it
+ is already deprecated, we force v2 cache for subpage.
+
+- Slightly higher memory usage for scrub
+ This is due to how we allocate pages for scrub, and will be fixed in the coming
+ releases soon.
The current subpage support in v5.18 has several limits, the most obvious ones are: - Only support 64KiB page size - No RAID56 support The supports are already queued for v5.19. And some minor ones: - No inline extent write support Read is always supported. Subpage mount will always just act as "max_inline=0". - Compression write is only for page aligned range. Read is always supported, no matter the alignment. - Extra memory usage for scrub Patchset is hanging there for a while though. Signed-off-by: Qu Wenruo <wqu@suse.com> --- Documentation/Subpage.rst | 59 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 3 deletions(-)