Re: [PATCH v2] qapi: Cleanup SGX related comments and restore @section-size

["Daniel P. Berrangé" <berrange@redhat.com>]

On Thu, Jan 20, 2022 at 04:31:14PM +0100, Philippe Mathieu-Daudé wrote:
> On 20/1/22 10:10, Daniel P. Berrangé wrote:
> > On Wed, Jan 19, 2022 at 06:57:20PM -0500, Yang Zhong wrote:
> > > The SGX NUMA patches were merged into Qemu 7.0 release, we need
> > > clarify detailed version history information and also change
> > > some related comments, which make SGX related comments clearer.
> > > 
> > > The QMP command schema promises backwards compatibility as standard.
> > > We temporarily restore "@section-size", which can avoid incompatible
> > > API breakage. The "@section-size" will be deprecated in 7.2 version.
> > > 
> > > Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
> > > Signed-off-by: Yang Zhong <yang.zhong@intel.com>
> > > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> > > ---
> > >   qapi/machine.json     |  4 ++--
> > >   qapi/misc-target.json | 17 ++++++++++++-----
> > >   hw/i386/sgx.c         | 11 +++++++++--
> > >   3 files changed, 23 insertions(+), 9 deletions(-)
> 
> > > diff --git a/qapi/misc-target.json b/qapi/misc-target.json
> > > index 1022aa0184..a87358ea44 100644
> > > --- a/qapi/misc-target.json
> > > +++ b/qapi/misc-target.json
> > > @@ -344,9 +344,9 @@
> > >   #
> > >   # @node: the numa node
> > >   #
> > > -# @size: the size of epc section
> > > +# @size: the size of EPC section
> > >   #
> > > -# Since: 6.2
> > > +# Since: 7.0
> > >   ##
> > >   { 'struct': 'SGXEPCSection',
> > >     'data': { 'node': 'int',
> > > @@ -365,7 +365,9 @@
> > >   #
> > >   # @flc: true if FLC is supported
> > >   #
> > > -# @sections: The EPC sections info for guest
> > > +# @section-size: The EPC section size for guest (Will be deprecated in 7.2)
> > 
> > I expected deprecation would start now (7.0, and it would be removed
> > in 7.2.
> > 
> > Also needs to be documented in docs/about/deprecated.rst
> 
> Isn't docs/about/deprecated.rst for user-facing changes *only*?
> 
> Machine-facing changes are already described in the QAPI schema.
> 
> Please correct me.

Just because something is machine-facing, doesn't mean it isn't
also user-facing, as users' write the machines that talk to QEMU.

deprecated.rst documents *everything* that changes in one of our
publically consumable interfaces, whether CLI args, QAPI schema,
HMP commands, or device impls or more. There's a whole section
there just for QMP command changes already.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|