Re: [PATCH for-4.6 4/8] docs/libxl: Re-specify XENSTORE_DATA as EMULATOR_XENSTORE_DATA

[David Vrabel <david.vrabel@citrix.com>]

On 28/07/15 22:44, Andrew Cooper wrote:
> The legacy "toolstack" record as implemented in libxl turns out not to
> be 32/64bit safe.  As migration v2 has not shipped yet, take this
> opportunity to adjust the specification and fix the incompatibility.
> 
> Libxl shall loose all knowledge of the old "toolstack" blob and use this
> EMULATOR_XENSTORE_DATA record instead.  Compatibility shall be handled
> by the legacy conversion script.
[...]
> +EMULATOR\_XENSTORE\_DATA
> +------------------------
>  
> -A record containing xenstore key/value pairs of data.
> +A set of xenstore key/value pairs for a specific emulator associated with the
> +domain.
>  
>       0     1     2     3     4     5     6     7 octet
> -    +-------------------------------------------------+
> -    | xenstore key/value pairs                        |
> +    +------------------------+------------------------+
> +    | emulator_id            | index                  |
> +    +------------------------+------------------------+
> +    | xenstore key/value data                         |
>      ...
>      +-------------------------------------------------+
>  
> +Xenstore key and value data are encoded as a pair of NUL terminated C
> +strings.  Keys shall be relative to to the device models xenstore tree for the
> +new domain

This isn't quite descriptive enough, suggest:

   "Xenstore key/value data is encoded as a packed sequence of (key,
    value) tuples.  Each (key, value) tuple is a packed pair of NUL
    terminated UTF-8 encoded character strings.  The keys are relative
    to..."

In particular, it is essential that character strings have a well
defined encoding (I always recommend UTF-8) but the Xenstore protocol
may specify a different encoding (perhaps ASCII?).  The data may also be
better specified as a NULL-terminated octet sequence (rather than
characters).

> +
> +i.e. relative to `/local/domain/$dm_domid/device-model/$domid/`
> +
> +The _emulator\_id_ and _index_ have the same meaning as the
> +**EMULATOR\_CONTEXT** record.
> +
>  EMULATOR\_CONTEXT
>  ----------------
>