Re: [Xen-devel] [PATCH 11 of 11] Some automatic NUMA placement documentation

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

Dario Faggioli writes ("[PATCH 11 of 11] Some automatic NUMA placement 
documentation"):
> About rationale, usage and API.
...
> +## Guest Placement in libxl ##

Oh here's the API documentation!

In general I would prefer to see docs come in the same patch but I
guess I can read it here:

> +xl achieves automatic NUMA placement by means of the following API
> +calls, provided by libxl.

Can you try to write some more general comment about what order these
functions should be called in ?

Or to put it another way:

> +        libxl_numa_candidate *libxl_domain_numa_candidates(libxl_ctx *ctx,
> +                                            libxl_domain_build_info *b_info,
> +                                            int min_nodes, int *nr_cndts);
> +
> +This is what should be used to generate the full set of placement
> +candidates. In fact, the function returns an array of containing nr_cndts
> +libxl_numa_candidate (see below). Each candidate is basically a set of nodes
> +that has been checked against the memory requirement derived from the
> +provided libxl_domain_build_info.

That tells me what the function does.  But my starting point is that I
have no idea when or why I might want to `generate the full set of
placement candidates'.  If this is something I need to do the docs
need to explain that.

This goes double for this function:

> +        int libxl_numa_candidate_add_cpus(libxl_ctx *ctx,
> +                                          int min_cpus, int max_nodes,
> +                                          libxl_numa_candidate *candidate);
> +
> +This is what should be used to ensure a placement candidate has at least
> +min_cpus CPUs. In case it does not, the function also take care of
> +adding more nodes to the candidate itself (up to when the value specified
> +in max_nodes is reached). When adding new nodes, the one that has the
> +smallest "distance" from the current node map is selected at each step.

`add_cpus' doesn't seem the same as `ensure a candidate has at least
min_cpus CPUs'.  In what sense are the CPUs added ?


And, as before, why might I want to call this ?  And when would I call
it ?  Why does the interface to libxl expose this rather than just
offering a single function

 libxl_do_automatic_numa_placement_according_to_heuristics

?


> +        libxl_numa_candidate_count_domains(libxl_ctx *ctx,
> +                                           libxl_numa_candidate *candidate);
> +
> +This is what counts the number of domains that are currently pinned
> +to the CPUs of the nodes of a given candidate.

Why is that useful ?  It is used by some of your other code so I guess
this is a facility which is useful to the implementors of other
placement algorithms ?

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel