Re: [Xen-devel] [PATCH] libxl: Documentation about the domain configuration on disk

[Wei Liu <wei.liu2@xxxxxxxxxx>]

On Thu, Dec 06, 2018 at 10:43:32AM +0000, Anthony PERARD wrote:
> It isn't currently written how one is supposed to update the domain
> configuration in libxl's private data store. This patch attempt to
> document the unwritten rules.
> 
> Signed-off-by: Anthony PERARD <anthony.perard@xxxxxxxxxx>
> ---
>  tools/libxl/CODING_STYLE | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
> 
> diff --git a/tools/libxl/CODING_STYLE b/tools/libxl/CODING_STYLE
> index 3d572f6925..2ce8529c9b 100644
> --- a/tools/libxl/CODING_STYLE
> +++ b/tools/libxl/CODING_STYLE
> @@ -186,6 +186,30 @@ When using an ao sub-operation, you should normally:
>     cancel or destroy method.
>  
>  
> +UPDATE OF DOMAIN CONFIGURATION
> +------------------------------
> +
> +Also known as "libxl-json" userdata or `libxl_domain_config'.
> +
> +Whenever a running domain have its configuration updated, like changing
> +media in a cdrom drive, the domain configuration in libxl private data
> +store needs to be updated as well. The domain configuration should
> +contain *more* information about the domain rather than less, stale data
> +are easier to spot that missing data.
> +
> +Here is an example of how to update the domain configuration:
> + * Remove current media from cdrom drive
> + * Update domain configuration with media removed

We may not even need this because the primary source in this case is
QEMU. See below.

> + ( we could stop here)
> + * Update domain configuration to add media we are about to insert
> + * Insert media into cdrom drive

In essence we need a primary reference while using libxl-json file as a
secondary source.

When doing device hotplug, the primary source is xenstore. It may become
QEMU in the future if we move to a model where everything is
communicated via QMP.

When doing CDROM insertion and rejection, the primary source is QEMU
state.

All in all I think your description is not wrong but it failed to
capture the high-level intent -- always update libxl-json before
updating the primary source.

> +
> +Retrieve / store domain configuration from / to libxl private data store
> +are done with `libxl__get_domain_configuration' and
> +`libxl__set_domain_configuration'. Consult libxl_internal.h for more
> +information.
> +

What do you think about the text around libxl_internal.h:L2598? Maybe we
should extend that comment block?

Wei.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel