[xen staging] xen/public: add comment to struct xen_mem_acquire_resource

[patchbot@xxxxxxx]

commit f0f2f42c21de82ff65672e8ecfadcfddc63f2186
Author:     Juergen Gross <jgross@xxxxxxxx>
AuthorDate: Fri Feb 25 11:10:19 2022 +0100
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Fri Feb 25 11:10:19 2022 +0100

    xen/public: add comment to struct xen_mem_acquire_resource
    
    Commit 7c7f7e8fba01 changed xen/include/public/memory.h in an incompatible
    way. Unfortunately the changed parts were already in use in the Linux
    kernel, so an update of the header in the kernel would result in a build
    breakage.
    
    As the change of above commit was in a section originally meant to be not
    stable, it was the usage in the kernel which was wrong.
    
    Add a comment to the modified struct for not reusing the now removed bit,
    in order to avoid kernels using it stumbling over a possible new meaning
    of the bit.
    
    In case the kernel is updating to a new version of the header, the wrong
    use case must be removed first.
    
    Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
    Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
---
 xen/include/public/memory.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/xen/include/public/memory.h b/xen/include/public/memory.h
index 383a9468c3..a1a0f0233a 100644
--- a/xen/include/public/memory.h
+++ b/xen/include/public/memory.h
@@ -662,6 +662,13 @@ struct xen_mem_acquire_resource {
      * two calls.
      */
     uint32_t nr_frames;
+    /*
+     * Padding field, must be zero on input.
+     * In a previous version this was an output field with the lowest bit
+     * named XENMEM_rsrc_acq_caller_owned. Future versions of this interface
+     * will not reuse this bit as an output with the field being zero on
+     * input.
+     */
     uint32_t pad;
     /*
      * IN - the index of the initial frame to be mapped. This parameter
--
generated by git-patchbot for /home/xen/git/xen.git#staging