Re: [PATCH 17/17] docs: provide description for device_model_machine option

[Anthony PERARD <anthony.perard@xxxxxxxxxx>]

On Fri, Mar 13, 2026 at 04:35:05PM +0000, Thierry Escande wrote:
> This patch adds description for 'device_model_machine' option which allows
> to control which chipset will be emulated by device model.
> 
> Signed-off-by: Alexey Gerasimenko <x1917x@xxxxxxxxx>
> Signed-off-by: Thierry Escande <thierry.escande@xxxxxxxxxx>
> ---
>  docs/man/xl.cfg.5.pod.in | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
> 
> diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in
> index 27c455210b..67a5bc54a5 100644
> --- a/docs/man/xl.cfg.5.pod.in
> +++ b/docs/man/xl.cfg.5.pod.in
> @@ -2963,6 +2963,33 @@ you have existing guests then, depending on the nature 
> of the guest
>  Operating System, you may wish to force them to use the device
>  model which they were installed with.
>  
> +=item B<device_model_machine="STRING">
> +
> +Selects which chipset the device model should emulate for this
> +guest.
> +
> +Valid options are:
> +
> +=over 4
> +
> +=item B<"i440">
> +
> +Use i440 emulation (a default setting)

Just "(default)" or even nothing is fine too.

I don't think we can say "i440" here, QEMU code always reference to it
as "i440FX", and if you want to specify the south bridge like you do
below, it would be "i440FX/PIIX3".

> +
> +=item B<"q35">
> +
> +Use Q35/ICH9 emulation. This enables additional features for
> +PCIe device passthrough

Could you add a full stop, to finish the sentence?

> +=back
> +
> +Note that omitting device_model_machine parameter means i440 system
> +by default,

Just saying "The default is B<"i440fx"> should be enough. No need to
explain when a default is selected.

> so the default behavior doesn't change for old domain
> +config files.

I don't think this explanation belong here.

> +It is recommended to install the guest OS from scratch to avoid issues
> +due to the emulated platform change.

I don't think this belong to the man page because they are other setting
that could prevent a guest from booting, when changed. Also I don't
think Linux cares. I'm not sure saying that changing this particular
setting could break existing guest would be a useful addition to this
particular setting description, as I'm sure that also true to quite a
few other settings.

On the other hand, there's a warning for `device_model_version`, about
existing guest, and default value that have changed.

So it's probably good enough to say that changing this new setting could
prevent existing guest from booting, and a fresh new installation
might be needed.

Also installing Linux From Scratch would be quite and endeavor :-)
  https://www.linuxfromscratch.org/


Cheers,


--
Anthony Perard | Vates XCP-ng Developer

XCP-ng & Xen Orchestra - Vates solutions

web: https://vates.tech