Re: [PATCH v4 11/34] xsplice: Design document

["Jan Beulich" <JBeulich@suse.com>]

>>> On 15.03.16 at 18:56, <konrad.wilk@oracle.com> wrote:
> +### XEN_SYSCTL_XSPLICE_LIST (2)
> +
> +Retrieve an array of abbreviated status and names of payloads that are 
> loaded in the
> +hypervisor.
> +
> +The caller provides:
> +
> + * `version`. Initially (on first hypercall) *MUST* be zero.
> + * `idx` index iterator. On first call *MUST* be zero, subsequent calls varies.
> + * `nr` the max number of entries to populate.
> + * `pad` - *MUST* be zero.
> + * `status` virtual address of where to write `struct xen_xsplice_status`
> +   structures. Caller *MUST* allocate up to `nr` of them.
> + * `name` - virtual address of where to write the unique name of the payload.
> +   Caller *MUST* allocate up to `nr` of them. Each *MUST* be of
> +   **XEN_XSPLICE_NAME_SIZE** size.
> + * `len` - virtual address of where to write the length of each unique name
> +   of the payload. Caller *MUST* allocate up to `nr` of them. Each *MUST* be
> +   of sizeof(uint32_t) (4 bytes).
> +
> +If the hypercall returns an positive number, it is the number (upto `nr`
> +provided to the hypercall) of the payloads returned, along with `nr` updated
> +with the number of remaining payloads, `version` updated (it may be the same
> +across hypercalls - if it varies the data is stale and further calls could
> +fail). The `status`, `name`, and `len`' are updated at their designed index
> +value (`idx`) with the returned value of data.
> +
> +If the hypercall returns -XEN_E2BIG the `nr` is too big and should be
> +lowered.
> +
> +If the hypercall returns an zero value there are no more payloads.
> +
> +Note that due to the asynchronous nature of hypercalls the control domain might
> +have added or removed a number of payloads making this information stale. It is
> +the responsibility of the toolstack to use the `version` field to check
> +between each invocation. if the version differs it should discard the stale
> +data and start from scratch. It is OK for the toolstack to use the new
> +`version` field.
> +
> +The `struct xen_xsplice_status` structure contains an status of payload which includes:
> +
> + * `status` - indicates the current status of the payload:
> +   * *XSPLICE_STATUS_CHECKED*  (1) loaded and the ELF payload safety checks passed.
> +   * *XSPLICE_STATUS_APPLIED* (2) loaded, checked, and applied.
> +   *  No other value is possible.
> + * `rc` - -XEN_EXX type errors encountered while performing the last
> +   XSPLICE_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
> +   respectively mean: success or operation in progress. Other values
> +   imply an error occurred. If there is an error in `rc`, `status` will **NOT**
> +   have changed.
> +
> +The structure is as follow:
> +
> +<pre>
> +struct xen_sysctl_xsplice_list {  
> +    uint32_t version;                       /* IN/OUT: Initially *MUST* be zero.  
> +                                               On subsequent calls reuse value.  
> +                                               If varies between calls, we are  
> +                                             * getting stale data. */  
> +    uint32_t idx;                           /* IN/OUT: Index into array. */ 
> +    uint32_t nr;                            /* IN: How many status, names, and len  
> +                                               should fill out.  
> +                                               OUT: How many payloads left. */  

I think there's an ambiguity left in both the description above and
the comments here: With idx required to be zero upon first
invocation (which I'm not clear why that is), which parts of the
three arrays get filled when idx is non-zero: [0, idx) or [nr, nr + idx)?

Jan


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