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

[patchbot@xxxxxxx]

commit 3f6ee3db2e878398cfcde725399b4d1b04e92269
Author:     Juergen Gross <jgross@xxxxxxxx>
AuthorDate: Tue Oct 15 14:24:45 2024 +0200
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Tue Oct 15 14:24:45 2024 +0200

    xen/public: add comments regarding interface version bumps
    
    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@xxxxxxxx>
    Reviewed-by: Jan Beulich <jbeulich@xxxxxxxx>
    Acked-by: Julien Grall <jgrall@xxxxxxxxxx>
---
 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
 
 /*
--
generated by git-patchbot for /home/xen/git/xen.git#staging