[libvirt] [PATCH v2 22/21] docs: Improve documentation for serial consoles

[Pavel Hrdina]

On Fri, Nov 24, 2017 at 11:35:01AM +0100, Andrea Bolognani wrote:
> On Thu, 2017-11-23 at 18:05 +0100, Pavel Hrdina wrote:
> > On Wed, Nov 22, 2017 at 04:24:07PM +0100, Andrea Bolognani wrote:
> > > +    <p>
> > > +      Some of the values listed above are not compatible with all
> > > +      architecture and machine types, and if the value is missing altogether,
> > 
> > s/architecture/architectures/
> > 
> > > +      libvirt will try to pick an appropriate default. In general, it's a
> > > +      good idea to specify neither the target type nor the target model,
> > > +      leave the task of choosing values up to libvirt, and don't change the
> > > +      values afterward.
> > 
> > I would probably rephrase that to something like this:
> > 
> > Some of the values listed above are not compatible with all
> > architectures and machine types. If neither the target type nor
> > the target model is specified, libvirt will choose default values,
> > which are in general the best choice.
> > 
> > The original wording kind of feels strictly limiting and like you
> > shouldn't try to configure it at all.
> 
> Well, you kinda shouldn't :)
> 
> When I was writing that paragraph, I had this piece of existing
> documentation in mind:
> 
>   PCI controllers also have an optional subelement <model> with an
>   attribute name. [...] In almost all cases, you should not manually
>   add a <model> subelement to a controller, nor should you modify
>   one that is automatically generated by libvirt.
> 
> I believe the same applies here. There's exactly one situation where
> you'll want to change the model for a PCI controller (using ioh3420
> even though pcie-root-port is available) and exactly one situation
> where you'll want to change the model for a serial device (using
> sclplmconsole instead of sclpconsole on s390x).

It's similar but not the same.  In case of PCI I agree that it's best
for users not to mangle with the models unless you know what you are
doing, but for serial device on s390x we have two valid models where
you can pick whichever you like or prefer, the same like we have sound
models or video models.  That's why I would prefer different wording
which is not that restrictive.

Pavel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20171124/0c13a85a/attachment-0001.sig>