From mboxrd@z Thu Jan  1 00:00:00 1970
From: David Vrabel <david.vrabel@citrix.com>
Subject: Re: [PATCH for-4.6 4/8] docs/libxl: Re-specify
 XENSTORE_DATA as EMULATOR_XENSTORE_DATA
Date: Wed, 29 Jul 2015 10:35:52 +0100
Message-ID: <55B89E78.60701@citrix.com>
References: <1438119883-8083-1-git-send-email-andrew.cooper3@citrix.com>
	<1438119883-8083-5-git-send-email-andrew.cooper3@citrix.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Return-path: <xen-devel-bounces@lists.xen.org>
In-Reply-To: <1438119883-8083-5-git-send-email-andrew.cooper3@citrix.com>
List-Unsubscribe: <http://lists.xen.org/cgi-bin/mailman/options/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=unsubscribe>
List-Post: <mailto:xen-devel@lists.xen.org>
List-Help: <mailto:xen-devel-request@lists.xen.org?subject=help>
List-Subscribe: <http://lists.xen.org/cgi-bin/mailman/listinfo/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=subscribe>
Sender: xen-devel-bounces@lists.xen.org
Errors-To: xen-devel-bounces@lists.xen.org
To: Andrew Cooper <andrew.cooper3@citrix.com>, Xen-devel <xen-devel@lists.xen.org>
Cc: Wei Liu <wei.liu2@citrix.com>, Ian Jackson <Ian.Jackson@eu.citrix.com>, Ian Campbell <Ian.Campbell@citrix.com>
List-Id: xen-devel@lists.xenproject.org

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
>  ----------------
>