xen/public: add comments regarding interface version bumps

[PATCH] xen/public: add comments regarding interface version bumps

Posted by Juergen Gross 1 month, 1 week ago

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(+)

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
 
 /*
-- 
2.43.0

Re: [PATCH] xen/public: add comments regarding interface version bumps

Posted by Julien Grall 1 month, 1 week ago

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,

-- 
Julien Grall

Re: [PATCH] xen/public: add comments regarding interface version bumps

Posted by Jürgen Groß 1 month, 1 week ago

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

Re: [PATCH] xen/public: add comments regarding interface version bumps

Posted by Jan Beulich 1 month, 1 week ago

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

Re: [PATCH] xen/public: add comments regarding interface version bumps

Posted by Jan Beulich 1 month, 1 week ago

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>