| Message ID | 20241014103311.31272-1-jgross@suse.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | xen/public: add comments regarding interface version bumps | expand |
On 14.10.2024 12:33, Juergen Gross wrote: > domctl.h and sysctl.h have an interface version, which needs to be > bumped in case of incompatible modifications of the interface. > > In order to avoid misunderstandings, add a comment to both headers > specifying in which cases a bump is needed. > > Signed-off-by: Juergen Gross <jgross@suse.com> Reviewed-by: Jan Beulich <jbeulich@suse.com>
Hi Juergen, On 14/10/2024 11:33, Juergen Gross wrote: > domctl.h and sysctl.h have an interface version, which needs to be > bumped in case of incompatible modifications of the interface. What about vm_event.h? > > In order to avoid misunderstandings, add a comment to both headers > specifying in which cases a bump is needed. > > Signed-off-by: Juergen Gross <jgross@suse.com> Regardless my question above: Acked-by: Julien Grall <jgrall@amazon.com> Cheers,
On 14.10.24 12:48, Julien Grall wrote: > Hi Juergen, > > On 14/10/2024 11:33, Juergen Gross wrote: >> domctl.h and sysctl.h have an interface version, which needs to be >> bumped in case of incompatible modifications of the interface. > > What about vm_event.h? Indeed. There seem to be others missing, too. Here a git grep output of possible candidates (including domctl.h, sysctl.h and vm_event.h): arch-x86/xen-mca.h:#define XEN_MCA_INTERFACE_VERSION 0x01ecc003 domctl.h:#define XEN_DOMCTL_INTERFACE_VERSION 0x00000017 hvm/hvm_op.h:#define HVMOP_ALTP2M_INTERFACE_VERSION 0x00000001 platform.h:#define XENPF_INTERFACE_VERSION 0x03000001 sysctl.h:#define XEN_SYSCTL_INTERFACE_VERSION 0x00000015 vm_event.h:#define VM_EVENT_INTERFACE_VERSION 0x00000007 xsm/flask_op.h:#define XEN_FLASK_INTERFACE_VERSION 1 I can add another patch for the missing ones (or 1 patch for each?) > >> >> In order to avoid misunderstandings, add a comment to both headers >> specifying in which cases a bump is needed. >> >> Signed-off-by: Juergen Gross <jgross@suse.com> > > Regardless my question above: > > Acked-by: Julien Grall <jgrall@amazon.com> Thanks, Juergen
On 14.10.2024 13:01, Jürgen Groß wrote: > On 14.10.24 12:48, Julien Grall wrote: >> On 14/10/2024 11:33, Juergen Gross wrote: >>> domctl.h and sysctl.h have an interface version, which needs to be >>> bumped in case of incompatible modifications of the interface. >> >> What about vm_event.h? > > Indeed. > > There seem to be others missing, too. Here a git grep output of > possible candidates (including domctl.h, sysctl.h and vm_event.h): > > arch-x86/xen-mca.h:#define XEN_MCA_INTERFACE_VERSION 0x01ecc003 > domctl.h:#define XEN_DOMCTL_INTERFACE_VERSION 0x00000017 > hvm/hvm_op.h:#define HVMOP_ALTP2M_INTERFACE_VERSION 0x00000001 > platform.h:#define XENPF_INTERFACE_VERSION 0x03000001 > sysctl.h:#define XEN_SYSCTL_INTERFACE_VERSION 0x00000015 > vm_event.h:#define VM_EVENT_INTERFACE_VERSION 0x00000007 > xsm/flask_op.h:#define XEN_FLASK_INTERFACE_VERSION 1 > > I can add another patch for the missing ones (or 1 patch for each?) Please don't. The situation is different there. Sysctl and domctl are unstable interfaces, hence to change them in incompatible ways a bump is all that's needed (in addition). That's quite different from cases where the interface itself is stable. The only possible exception to this is vm_event.h, which offers solely tools-only interfaces. I'm not sure though whether "just" bumping the interface version there is enough for an incompatible change to occur. Tamas? Jan
diff --git a/xen/include/public/domctl.h b/xen/include/public/domctl.h index e1028fc524..353f831e40 100644 --- a/xen/include/public/domctl.h +++ b/xen/include/public/domctl.h @@ -21,6 +21,16 @@ #include "hvm/save.h" #include "memory.h" +/* + * The interface version needs to be incremented by 1 in case the interface + * is modified in an incompatible way AND if the version hasn't been + * incremented in the current development cycle already. + * Pure additions (e.g. new sub-commands) or compatible interface changes + * (e.g. adding semantics to 0-checked input fields or data to zeroed output + * fields) don't require a change of the version. + * + * Last version bump: Xen 4.19 + */ #define XEN_DOMCTL_INTERFACE_VERSION 0x00000017 /* diff --git a/xen/include/public/sysctl.h b/xen/include/public/sysctl.h index b2a5a724db..b0fec271d3 100644 --- a/xen/include/public/sysctl.h +++ b/xen/include/public/sysctl.h @@ -18,6 +18,16 @@ #include "domctl.h" #include "physdev.h" +/* + * The interface version needs to be incremented by 1 in case the interface + * is modified in an incompatible way AND if the version hasn't been + * incremented in the current development cycle already. + * Pure additions (e.g. new sub-commands) or compatible interface changes + * (e.g. adding semantics to 0-checked input fields or data to zeroed output + * fields) don't require a change of the version. + * + * Last version bump: Xen 4.17 + */ #define XEN_SYSCTL_INTERFACE_VERSION 0x00000015 /*
domctl.h and sysctl.h have an interface version, which needs to be bumped in case of incompatible modifications of the interface. In order to avoid misunderstandings, add a comment to both headers specifying in which cases a bump is needed. Signed-off-by: Juergen Gross <jgross@suse.com> --- xen/include/public/domctl.h | 10 ++++++++++ xen/include/public/sysctl.h | 10 ++++++++++ 2 files changed, 20 insertions(+)