[PATCH v10 07/11] libxl/xl: deprecate the build_info->cpumap field

[Dario Faggioli <dario.faggioli@citrix.com>]

as, thanks to previous change ("libxl/xl: push VCPU affinity
pinning down to libxl"), we now have an array of libxl_bitmap-s
that can be used to transfer to libxl the vcpu (hard) affinity
of each vcpu of the domain.

The cpumap field, used to provide libxl with just one cpumap
that should be applied to all vcpus, is therefore of no more
use. Actually, it is duplicated information and can lead to
confusion.

With this change, we make it even more clear that the preferred
way of specifying VCPU affinity is from now on, the vcpu_hard_affinity
array. To do so, mark the cpumap field as DEPRECATED. It still is
there, and it is still honoured, for backward compatibility reasons,
but it should no longer be used.

Signed-off-by: Dario Faggioli <dario.faggioli@citrix.com>
---
Changes from v9:
 * get rid of the xl part, which now lives in its separate
   patch, as requested during review;
 * updated the comment in libxl_types.idl, mentioning what
   happens if both cpumap and vcpu_hard_affinity are used,
   as requested during review.

Changes from v8:
 * don't get rid of b_info->cpumap handling, so old apps
   continue to work, as requested during review;
 * changelog and code comments updated accordingly.
---
 tools/libxl/libxl_dom.c     |    9 ++++++++-
 tools/libxl/libxl_types.idl |    8 +++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/tools/libxl/libxl_dom.c b/tools/libxl/libxl_dom.c
index 7a60ee2..81e77c0 100644
--- a/tools/libxl/libxl_dom.c
+++ b/tools/libxl/libxl_dom.c
@@ -283,9 +283,16 @@ int libxl__build_pre(libxl__gc *gc, uint32_t domid,
                 return ERROR_FAIL;
             }
         }
-    } else if (info->cpumap.size)
+    } else if (info->cpumap.size) {
+        /*
+         * Although info->cpumap is DEPRECATED, we still want old
+         * applications that may be using it to continue working.
+         */
+        LOG(WARN, "cpumap field of libxl_domain_build_info is DEPRECATED. "
+                  "Please, use the vcpu_hard_affinity array instead");
         libxl_set_vcpuaffinity_all(ctx, domid, info->max_vcpus,
                                    &info->cpumap, NULL);
+    }
 
 
     if (xc_domain_setmaxmem(ctx->xch, domid, info->target_memkb +
diff --git a/tools/libxl/libxl_types.idl b/tools/libxl/libxl_types.idl
index 5607ea7..477b2a6 100644
--- a/tools/libxl/libxl_types.idl
+++ b/tools/libxl/libxl_types.idl
@@ -301,7 +301,13 @@ libxl_domain_sched_params = Struct("domain_sched_params",[
 libxl_domain_build_info = Struct("domain_build_info",[
     ("max_vcpus",       integer),
     ("avail_vcpus",     libxl_bitmap),
-    ("cpumap",          libxl_bitmap),
+    ("cpumap",          libxl_bitmap), # DEPRECATED!
+    # The cpumap field above has been deprecated by the introduction of the
+    # vcpu_hard_affinity array. It is not removed and it is still honoured, for
+    # API stability and backward compatibility reasons, but should not be used
+    # any longer. The vcpu_hard_affinity array is what should be used instead.
+    # As per libxl.h, if both cpumap and vcpu_hard_affinity are used, the latter
+    # will prevail.
     ("nodemap",         libxl_bitmap),
     ("vcpu_hard_affinity", Array(libxl_bitmap, "num_vcpu_hard_affinity")),
     ("numa_placement",  libxl_defbool),