[v2] Documentation: block: zloop: clarify capacity alignment

[PATCH v2] Documentation: block: zloop: clarify capacity alignment

Posted by raoxu 1 month, 4 weeks ago

From: Xu Rao <raoxu@uniontech.com>

zloop divides the requested capacity by the zone size to determine the
number of zones. Since it uses one zone size for all zones, a smaller last
zone is not supported and an unaligned capacity is rounded down.

The capacity_mb description incorrectly states that the capacity is rounded
up. Correct it to document the actual behavior.

Fixes: 9e4f11c1228c ("Documentation: Document the new zoned loop block device driver")
Suggested-by: Damien Le Moal <dlemoal@kernel.org>
Signed-off-by: Xu Rao <raoxu@uniontech.com>
---
Changes in v2:
- Replace the code change with a documentation correction.
- State that a smaller last zone is unsupported and that an unaligned
  capacity is rounded down.

 Documentation/admin-guide/blockdev/zoned_loop.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/blockdev/zoned_loop.rst b/Documentation/admin-guide/blockdev/zoned_loop.rst
index f4f1f31..fd99e5c 100644
--- a/Documentation/admin-guide/blockdev/zoned_loop.rst
+++ b/Documentation/admin-guide/blockdev/zoned_loop.rst
@@ -71,8 +71,9 @@ follows.
 ===================   =========================================================
 id                    Device number (the X in /dev/zloopX).
                       Default: automatically assigned.
-capacity_mb           Device total capacity in MiB. This is always rounded up
-                      to the nearest higher multiple of the zone size.
+capacity_mb           Device total capacity in MiB. A smaller last zone is not
+                      supported, so an unaligned value is rounded down to a
+                      zone-size multiple.
                       Default: 16384 MiB (16 GiB).
 zone_size_mb          Device zone size in MiB. Default: 256 MiB.
 zone_capacity_mb      Device zone capacity (must always be equal to or lower
--
2.47.3

Re: [PATCH v2] Documentation: block: zloop: clarify capacity alignment

Posted by Damien Le Moal 1 month, 4 weeks ago

On 8/4/26 12:41, raoxu wrote:
> From: Xu Rao <raoxu@uniontech.com>
> 
> zloop divides the requested capacity by the zone size to determine the
> number of zones. Since it uses one zone size for all zones, a smaller last
> zone is not supported and an unaligned capacity is rounded down.
> 
> The capacity_mb description incorrectly states that the capacity is rounded
> up. Correct it to document the actual behavior.
> 
> Fixes: 9e4f11c1228c ("Documentation: Document the new zoned loop block device driver")
> Suggested-by: Damien Le Moal <dlemoal@kernel.org>
> Signed-off-by: Xu Rao <raoxu@uniontech.com>
> ---
> Changes in v2:
> - Replace the code change with a documentation correction.
> - State that a smaller last zone is unsupported and that an unaligned
>   capacity is rounded down.
> 
>  Documentation/admin-guide/blockdev/zoned_loop.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/admin-guide/blockdev/zoned_loop.rst b/Documentation/admin-guide/blockdev/zoned_loop.rst
> index f4f1f31..fd99e5c 100644
> --- a/Documentation/admin-guide/blockdev/zoned_loop.rst
> +++ b/Documentation/admin-guide/blockdev/zoned_loop.rst
> @@ -71,8 +71,9 @@ follows.
>  ===================   =========================================================
>  id                    Device number (the X in /dev/zloopX).
>                        Default: automatically assigned.
> -capacity_mb           Device total capacity in MiB. This is always rounded up
> -                      to the nearest higher multiple of the zone size.
> +capacity_mb           Device total capacity in MiB. A smaller last zone is not
> +                      supported, so an unaligned value is rounded down to a
> +                      zone-size multiple.

Let's make this a proper sentence:

capacity_mb		Device total capacity in MiB. A smaller last zone is not
			supported, so a capacity value that is not multiple of
			the zone size is rounded down to the closest multiple of
			the zone-size.

With that,

Reviewed-by: Damien Le Moal <dlemoal@kernel.org>

>                        Default: 16384 MiB (16 GiB).
>  zone_size_mb          Device zone size in MiB. Default: 256 MiB.
>  zone_capacity_mb      Device zone capacity (must always be equal to or lower
> --
> 2.47.3
> 
> 


-- 
Damien Le Moal
Western Digital Research

[PATCH v3] Documentation: block: zloop: clarify capacity alignment

Posted by raoxu 1 month, 4 weeks ago

From: Xu Rao <raoxu@uniontech.com>

zloop divides the requested capacity by the zone size to determine the
number of zones. Since it uses one zone size for all zones, a smaller last
zone is not supported and an unaligned capacity is rounded down.

The capacity_mb description incorrectly states that the capacity is rounded
up. Correct it to document the actual behavior.

Fixes: 9e4f11c1228c ("Documentation: Document the new zoned loop block device driver")
Suggested-by: Damien Le Moal <dlemoal@kernel.org>
Reviewed-by: Damien Le Moal <dlemoal@kernel.org>
Signed-off-by: Xu Rao <raoxu@uniontech.com>
---
Changes in v2:
- Replace the code change with a documentation correction.
- State that a smaller last zone is unsupported and that an unaligned
  capacity is rounded down.

Changes in v3:
- Reword the capacity_mb description as suggested by Damien.

 Documentation/admin-guide/blockdev/zoned_loop.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/blockdev/zoned_loop.rst b/Documentation/admin-guide/blockdev/zoned_loop.rst
index f4f1f3121bf9..abaf36f21945 100644
--- a/Documentation/admin-guide/blockdev/zoned_loop.rst
+++ b/Documentation/admin-guide/blockdev/zoned_loop.rst
@@ -71,8 +71,10 @@ follows.
 ===================   =========================================================
 id                    Device number (the X in /dev/zloopX).
                       Default: automatically assigned.
-capacity_mb           Device total capacity in MiB. This is always rounded up
-                      to the nearest higher multiple of the zone size.
+capacity_mb           Device total capacity in MiB. A smaller last zone is not
+                      supported, so a capacity value that is not a multiple of
+                      the zone size is rounded down to the closest multiple of
+                      the zone size.
                       Default: 16384 MiB (16 GiB).
 zone_size_mb          Device zone size in MiB. Default: 256 MiB.
 zone_capacity_mb      Device zone capacity (must always be equal to or lower
--
2.50.1

Re: [PATCH v3] Documentation: block: zloop: clarify capacity alignment

Posted by Jens Axboe 1 month, 4 weeks ago

On Tue, 04 Aug 2026 13:29:41 +0800, raoxu wrote:
> zloop divides the requested capacity by the zone size to determine the
> number of zones. Since it uses one zone size for all zones, a smaller last
> zone is not supported and an unaligned capacity is rounded down.
> 
> The capacity_mb description incorrectly states that the capacity is rounded
> up. Correct it to document the actual behavior.
> 
> [...]

Applied, thanks!

[1/1] Documentation: block: zloop: clarify capacity alignment
      commit: d73b5b0690e36b2a9e6022f6712e9fa7fd338632

Best regards,
-- 
Jens Axboe

Re: [PATCH v3] Documentation: block: zloop: clarify capacity alignment

Posted by Christoph Hellwig 1 month, 4 weeks ago

Looks good:

Reviewed-by: Christoph Hellwig <hch@lst.de>