Re: [Qemu-devel] [PATCH v5 18/22] s390x: implement query-hotpluggable-cpus

["Marc-André Lureau" <marcandre.lureau@redhat.com>]

Hi

----- Original Message -----
> Cornelia Huck <cohuck@redhat.com> writes:
> 
> > On Wed, 04 Oct 2017 14:42:55 +0200
> > Markus Armbruster <armbru@redhat.com> wrote:
> >
> >> Cornelia Huck <cohuck@redhat.com> writes:
> >> 
> >> > On Mon, 02 Oct 2017 09:46:41 +0200
> >> > Markus Armbruster <armbru@redhat.com> wrote:
> >> >  
> >> >> David Hildenbrand <david@redhat.com> writes:
> >> >>   
> >> >> > CPU hotplug is only possible on a per core basis on s390x. So let's
> >> >> > add possible_cpus and properly wire everything up.
> >> >> >
> >> >> > Signed-off-by: David Hildenbrand <david@redhat.com>
> >> >> [...]
> >> >> > diff --git a/qapi-schema.json b/qapi-schema.json
> >> >> > index f3af2cb851..79e9f85404 100644
> >> >> > --- a/qapi-schema.json
> >> >> > +++ b/qapi-schema.json
> >> >> > @@ -3121,6 +3121,22 @@
> >> >> >  #      }
> >> >> >  #    ]}
> >> >> >  #
> >> >> > +# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2
> >> >> > -cpu qemu
> >> >> > +# (Since: 2.11):
> >> >> > +#
> >> >> > +# -> { "execute": "query-hotpluggable-cpus" }
> >> >> > +# <- {"return": [
> >> >> > +#      {
> >> >> > +#         "type": "qemu-s390-cpu", "vcpus-count": 1,
> >> >> > +#         "props": { "core-id": 1 }
> >> >> > +#      },
> >> >> > +#      {
> >> >> > +#         "qom-path": "/machine/unattached/device[0]",
> >> >> > +#         "type": "qemu-s390-cpu", "vcpus-count": 1,
> >> >> > +#         "props": { "core-id": 0 }
> >> >> > +#      }
> >> >> > +#    ]}
> >> >> > +#
> >> >> >  ##
> >> >> >  { 'command': 'query-hotpluggable-cpus', 'returns':
> >> >> >  ['HotpluggableCPU'] }
> >> >> 
> >> >> Please stick in '# Example:' like we do in query-hotpluggable-cpus's
> >> >> doc
> >> >> comment.  I expect the generated documentation to be illegible[*]
> >> >> without it.
> >> >
> >> > Should '# Example:' go before each of the examples (instead of the
> >> > beginning of the example block), then?
> >> 
> >> Whatever makes the generated documentation look better.
> >
> > The pdf indeed looks ugly, but that's a preexisting problem, and adding
> > more '# Example:' lines does not really help.
> >
> > The basic issue is that the code expects just one example and no
> > additional text for the '# Example:' tag -- the explaining text for the
> > various statements ends up looking like the qmp examples. That should
> > be improved before doing a patch on top for this command (and I don't
> > really have the skills or time to improve the output, sorry.)
> 
> Marc-André, any ideas?
> 

It's not supported atm. The ideas to fix this are pretty much a matter of taste.

I'd suggest to keep the code below the Example: section as @example/verbatim by default. And introduce a new section syntax, like Example:: to do "manual" formatting.

Example::

This text would be in regular format.
1. and allow list, *strong* etc.

| -> { then have some code }
| <- ...

And regulat text again.