RE: [PATCH v4 05/10] xen/domain: Add DOMCTL handler for claiming memory with NUMA awareness

[Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>]

> Should we state that the old interface is "deprecated" (somehow), and that
> people should take a look at XEN_DOMCTL_claim_memory instead, especially if
> they need a NUMA-aware interface ?
> That could be a note on the XENMEM_claim_memory hypercall.

Yes. People looking at the then obsolete XENMEM_claim_pages interface
should be referred to the new hypercall using such note.

In preparation for a follow-up, I appended an initial patch to add such
Notes (maybe also in libxc, memory_op and OCaml bindings) to refer people
to the new hypercall interface.

Best, Bernhard

--- a/xen/include/public/memory.h
+++ b/xen/include/public/memory.h
@@ -569,6 +569,15 @@ DEFINE_XEN_GUEST_HANDLE(xen_mem_sharing_op_t);
  * for 10, only 7 additional pages are claimed.
  *
  * Caller must be privileged or the hypercall fails.
+ *
+ * Note: This hypercall is deprecated by introducing XEN_DOMCTL_claim_memory
+ * which provides the same claim semantics described above, and thus can be
+ * used as drop-in replacement and is extended for NUMA-node-specific claims.
+ * This hypercall should not be used by new code.
+ *
+ * See the following documentation pages for more information:
+ * docs/guest-guide/dom/DOMCTL_claim_memory.rst
+ * docs/guest-guide/mem/XENMEM_claim_pages.rst
  */
 #define XENMEM_claim_pages                  24

--- a/docs/guest-guide/mem/XENMEM_claim_pages.rst
+++ b/docs/guest-guide/mem/XENMEM_claim_pages.rst
@@ -5,8 +5,9 @@ XENMEM_claim_pages
 ==================
 
 This **xenmem** command allows a privileged guest to stake a memory claim for a
-domain, identical to :ref:`XEN_DOMCTL_claim_memory`, but without support for
-NUMA-aware memory claims.
+domain, identical to :ref:`XEN_DOMCTL_claim_memory`, which is extended for
+NUMA-aware claims. XENMEM_claim_pages should not be used for new code and is
+deprecated. :ref:`XEN_DOMCTL_claim_memory` provides the same claims semantics.

 Memory claims in Xen
 --------------------