[RFC,1/4] docs/qcow2: add the zoned format feature

Add the specs for the zoned format feature of the qcow2 driver. Once
the zoned_profile is set to `zbc`, then the qcow2 file can be taken
as zoned devices and passed through by virtio-blk device to the guest.

Signed-off-by: Sam Li <faithilikerun@gmail.com>
---
 docs/system/qemu-block-drivers.rst.inc | 31 ++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

On Mon, Jun 05, 2023 at 06:41:05PM +0800, Sam Li wrote:
> Add the specs for the zoned format feature of the qcow2 driver. Once
> the zoned_profile is set to `zbc`, then the qcow2 file can be taken
> as zoned devices and passed through by virtio-blk device to the guest.
> 
> Signed-off-by: Sam Li <faithilikerun@gmail.com>
> ---
>  docs/system/qemu-block-drivers.rst.inc | 31 ++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)
> 
> diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
> index 105cb9679c..fdcf343652 100644
> --- a/docs/system/qemu-block-drivers.rst.inc
> +++ b/docs/system/qemu-block-drivers.rst.inc
> @@ -172,6 +172,37 @@ This section describes each format and the options that are supported for it.
>      filename`` to check if the NOCOW flag is set or not (Capital 'C' is
>      NOCOW flag).
>  
> +  .. option:: zoned_profile
> +
> +    The option configures the zoned format feature on the qcow2 driver. If
> +    this is set to ``zbc``, then it follows the basics of ZBC/ZAC protocol.

What about virtio-blk? NVMe ZNS? Please indicate what effect the profile
has and whether it works with all emulated storage controllers that
support zoned storage.

> +
> +  .. option:: zone_size
> +
> +    The size of a zone of the zoned device. The zoned device have the same

"in bytes"? Please document the units.

> +    size of zones with an optional smaller last zone.

"The device is divided into zones of this size with the exception of the
last zone, which may be smaller."

> +
> +  .. option:: zone_capacity
> +
> +    The capacity of a zone of the zoned device.

This can be expanded:

  The initial capacity value for all zones. The capacity must be less
  than or equal to zone size. If the last zone is smaller, then its
  capacity is capped.

> The zoned device follows the
> +    ZBC protocol tends to have the same size as its zone.
> +
> +  .. option:: zone_nr_conv
> +
> +    The number of conventional zones of the zoned device.
> +
> +  .. option:: max_open_zones
> +
> +    The maximal allowed open zones.
> +
> +  .. option:: max_active_zones
> +
> +    The limit of the zones with implicit open, explicit open or closed state.
> +
> +  .. option:: max_append_sectors
> +
> +    The maximal sectors that is allowed to append to zones while writing.

Does "sectors" mean 512B blocks or logical block size?

> +
>  .. program:: image-formats
>  .. option:: qed
>  
> -- 
> 2.40.1
>

Stefan Hajnoczi <stefanha@redhat.com> 于2023年6月13日周二 15:04写道：
>
> On Mon, Jun 05, 2023 at 06:41:05PM +0800, Sam Li wrote:
> > Add the specs for the zoned format feature of the qcow2 driver. Once
> > the zoned_profile is set to `zbc`, then the qcow2 file can be taken
> > as zoned devices and passed through by virtio-blk device to the guest.
> >
> > Signed-off-by: Sam Li <faithilikerun@gmail.com>
> > ---
> >  docs/system/qemu-block-drivers.rst.inc | 31 ++++++++++++++++++++++++++
> >  1 file changed, 31 insertions(+)
> >
> > diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
> > index 105cb9679c..fdcf343652 100644
> > --- a/docs/system/qemu-block-drivers.rst.inc
> > +++ b/docs/system/qemu-block-drivers.rst.inc
> > @@ -172,6 +172,37 @@ This section describes each format and the options that are supported for it.
> >      filename`` to check if the NOCOW flag is set or not (Capital 'C' is
> >      NOCOW flag).
> >
> > +  .. option:: zoned_profile
> > +
> > +    The option configures the zoned format feature on the qcow2 driver. If
> > +    this is set to ``zbc``, then it follows the basics of ZBC/ZAC protocol.
>
> What about virtio-blk? NVMe ZNS? Please indicate what effect the profile
> has and whether it works with all emulated storage controllers that
> support zoned storage.

The ZNS profile hasn't been included in this patch series yet.

Both ZNS and ZBC profiles can be used as the backing file for
virtio-blk passthrough. Though the NVMe controller with ZNS can only
use the ZNS profile. The ZNS profile can have a smaller size of
zoned_capacity than zone_size and only allows sequential write
required zoned type.

>
> > +
> > +  .. option:: zone_size
> > +
> > +    The size of a zone of the zoned device. The zoned device have the same
>
> "in bytes"? Please document the units.
>
> > +    size of zones with an optional smaller last zone.
>
> "The device is divided into zones of this size with the exception of the
> last zone, which may be smaller."
>
> > +
> > +  .. option:: zone_capacity
> > +
> > +    The capacity of a zone of the zoned device.
>
> This can be expanded:
>
>   The initial capacity value for all zones. The capacity must be less
>   than or equal to zone size. If the last zone is smaller, then its
>   capacity is capped.
>
> > The zoned device follows the
> > +    ZBC protocol tends to have the same size as its zone.
> > +
> > +  .. option:: zone_nr_conv
> > +
> > +    The number of conventional zones of the zoned device.
> > +
> > +  .. option:: max_open_zones
> > +
> > +    The maximal allowed open zones.
> > +
> > +  .. option:: max_active_zones
> > +
> > +    The limit of the zones with implicit open, explicit open or closed state.
> > +
> > +  .. option:: max_append_sectors
> > +
> > +    The maximal sectors that is allowed to append to zones while writing.
>
> Does "sectors" mean 512B blocks or logical block size?

According to virtio spec, it means 512B blocks.

Thanks!

>
> > +
> >  .. program:: image-formats
> >  .. option:: qed
> >
> > --
> > 2.40.1
> >