Subpage support
===============

Subpage block size support, or just *subpage* for short, is a feature to allow
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.

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 initial subpage support has been 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 a mount will be rejected 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.