[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v2 1/2] docs: fusa: Define the requirements for XEN_VERSION hypercall.


  • To: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
  • From: Bertrand Marquis <Bertrand.Marquis@xxxxxxx>
  • Date: Thu, 27 Feb 2025 17:15:28 +0000
  • Accept-language: en-GB, en-US
  • Arc-authentication-results: i=2; mx.microsoft.com 1; spf=pass (sender ip is 63.35.35.123) smtp.rcpttodomain=lists.xenproject.org smtp.mailfrom=arm.com; dmarc=pass (p=none sp=none pct=100) action=none header.from=arm.com; dkim=pass (signature was verified) header.d=arm.com; arc=pass (0 oda=1 ltdi=1 spf=[1,1,smtp.mailfrom=arm.com] dkim=[1,1,header.d=arm.com] dmarc=[1,1,header.from=arm.com])
  • Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none
  • Arc-message-signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector10001; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=sfmNHIYQFMe6MV/WsIo1vDK6reoLe4R/aCTzycqNA0Q=; b=PRAi4JbXAbqhCLf5rdLDv/R5glYmox/pxY4FbnsnUTTp9sTMF4T4g5tQmjOxlV+zgNJMQLz0LQV/o6rLFhuhZ7zb2QEiS7eGh2/4SIQ0D5xqDqo+bYBPfH8eWEqNIqW/DbAOYr96FAQbtP0h5LsK7hv+tw1wxKw/qeU7WKhijQ29BztpkCxrIAVjC/mXeTXGAXqiSgFm9uSzuFG7lpZMls8iNz1q1bJt/TAHBcWZPKR7e6eJG0MB2BE2VjsubVudc97ksj6uqX424cdai3vp777GGpg3VFw2UNl1TGFBE10NXxFdjjsON4vJEAKd6pur9wqf95i3Ssf2ZLj9MTPhyw==
  • Arc-message-signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector10001; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=sfmNHIYQFMe6MV/WsIo1vDK6reoLe4R/aCTzycqNA0Q=; b=ihcnXfS1sculyFj4+8CjeHw0kjCnhAFhFU+Trd0bOcKda98DZt2mq+zvCx3O8S7zv9qcaXHyxqNXBWsvyGgl9pXE3fpVhiPedw1p5elvM4oEzAZAOIyjeky0kfp48fTKi+8WeMeDp6Xmq9WclFOlab6VL0xPjpgihN0m878IMaHIN45Q9vYvOcQDvpl2OFBA1HAYmb4AFVWL+Ux3QslYWmPQiH687Rav4GteymxlPPlezb88w3lZnkzFoUX1gGFLFV7JQuBKJLAMVoopk+TNY45WRqUnAXa/zEkwKXBMsCrKFS85GgE1u3pgge/T6DPosJ0Q5F/arGIMUV5IB0JY9g==
  • Arc-seal: i=2; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=pass; b=Mtx1D+DfyCjjd7VvkZaGbkVagfmDcpzAq3Kb9R3Yvta71YyMptGU7frOWnlIS/daoDKTXRmPxqjhu8ZoJGACFEZGEkWJPyuZHMLVF7M4OJiC/WY0MiFn6QSJkDcoHbmec3jH/4B3z6JWGyNV7BOUzMFSNwxWPmj5idQ0K0s8M1Gf7gA1+NUG5QfJZdk5sEspqNYEoCQ+RW7zHFXiNj03mCjOpT/ISp9hYt3vF6tXfd2M+L9PXpGuYrdCLwIHXKWCqlvL1+q9m5GmxgOf3sXMA6y3ravrflf2ETO4vg9xyJvxha0huBenEiYwgiqApjM2wvTTcBSKaZ8SqFbIBbSwjA==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=MbAgCCTjX0dlCNVVYhkUCnYyD+JJUY1RwkHGce7POYeOjHZsGMA1esJUOLrNWiO1HOX++ncCWSIqQM9s4TxgLgDJPVOmc+mEKAqaYI4lZQB2UPtaTFRr2a5nT7GBzsgEsZZ5zxYHwNUa/XjRjf8dr5o6OiGO+BlStCcMwamHQNxHzNgwJR1nCPa3Lf4JG9SPgRPHor3zREitPv8ZlAjdglvoz3GTpPfEbxYzA1d036ZcUHDJZorCPyMDr/xxHkyZg0G1ajTDXNscf1qkHMLRQ7dBqDDHHpWga0753TQZ6uYwxAM8ASYfPFNvi8DBBlrBmzbzk6GALhyekrBWwrIFAA==
  • Authentication-results-original: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=arm.com;
  • Cc: "xen-devel@xxxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxxx>, Stefano Stabellini <sstabellini@xxxxxxxxxx>, Michal Orzel <michal.orzel@xxxxxxx>, Artem Mygaiev <artem_mygaiev@xxxxxxxx>
  • Delivery-date: Thu, 27 Feb 2025 17:15:51 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Nodisclaimer: true
  • Original-authentication-results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=arm.com;
  • Thread-index: AQHbiSmfhnajI8fAUU6893mrw5oGSLNbZAUA
  • Thread-topic: [PATCH v2 1/2] docs: fusa: Define the requirements for XEN_VERSION hypercall.

Hi Ayan,

> On 27 Feb 2025, at 16:09, Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx> wrote:
> 
> In the current patch, we have defined the requirements which are common for
> all the commands.
> 
> Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
> ---
> Changes from -
> 
> v1 - 1. Fixed `XenProd~version_hyp_ret_val~1` requirement as Xen does not 
> return
> 0 for success in all the cases.
> 2. Reworded the requirements so as to write them from Xen's perspective (not
> domain's perspective).
> 
> .../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
> docs/fusa/reqs/index.rst                      |  2 +
> docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
> .../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
> 4 files changed, 134 insertions(+)
> create mode 100644 docs/fusa/reqs/design-reqs/arm64/hypercall.rst
> create mode 100644 docs/fusa/reqs/product-reqs/version_hypercall.rst
> 
> diff --git a/docs/fusa/reqs/design-reqs/arm64/hypercall.rst 
> b/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
> new file mode 100644
> index 0000000000..ffd883260c
> --- /dev/null
> +++ b/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
> @@ -0,0 +1,55 @@
> +.. SPDX-License-Identifier: CC-BY-4.0
> +
> +Hypercall
> +=========
> +
> +Instruction
> +-----------
> +
> +`XenSwdgn~arm64_hyp_instr~1`
> +
> +Description:
> +Xen shall treat domain hypercall exception as hypercall requests.
> +
> +Rationale:
> +
> +Comments:
> +Hypercall is one of the communication mechanism between Xen and domains.
> +Domains use hypercalls for various requests to Xen.
> +Domains use 'hvc' instruction to invoke hypercalls.
> +
> +Covers:
> + - `XenProd~version_hyp_first_param~1`
> + - `XenProd~version_hyp_second_param~1`
> +
> +Parameters
> +----------
> +
> +`XenSwdgn~arm64_hyp_param~1`
> +
> +Description:
> +Xen shall use x0 to read the first parameter, x1 for second parameter and so
> +on, for domain hypercall requests.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~version_hyp_first_param~1`
> + - `XenProd~version_hyp_second_param~1`
> +
> +Return value
> +------------
> +
> +`XenSwdgn~arm64_ret_val~1`
> +
> +Description:
> +Xen shall store the return value in x0 register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~version_hyp_ret_val~1`
> diff --git a/docs/fusa/reqs/index.rst b/docs/fusa/reqs/index.rst
> index 1088a51d52..d8683edce7 100644
> --- a/docs/fusa/reqs/index.rst
> +++ b/docs/fusa/reqs/index.rst
> @@ -10,5 +10,7 @@ Requirements documentation
>    market-reqs/reqs
>    product-reqs/reqs
>    product-reqs/arm64/reqs
> +   product-reqs/version_hypercall
>    design-reqs/arm64/generic-timer
>    design-reqs/arm64/sbsa-uart
> +   design-reqs/arm64/hypercall
> diff --git a/docs/fusa/reqs/market-reqs/reqs.rst 
> b/docs/fusa/reqs/market-reqs/reqs.rst
> index 2d297ecc13..0e29fe5362 100644
> --- a/docs/fusa/reqs/market-reqs/reqs.rst
> +++ b/docs/fusa/reqs/market-reqs/reqs.rst
> @@ -79,3 +79,19 @@ Comments:
> 
> Needs:
>  - XenProd
> +
> +Version hypercall
> +-----------------
> +
> +`XenMkt~version_hypercall~1`
> +
> +Description:
> +Xen shall provide an interface for the domains to retrieve Xen's version, 
> type
> +and compilation information.
> +
> +Rationale:
> +
> +Comments:
> +
> +Needs:
> + - XenProd
> diff --git a/docs/fusa/reqs/product-reqs/version_hypercall.rst 
> b/docs/fusa/reqs/product-reqs/version_hypercall.rst
> new file mode 100644
> index 0000000000..03221f70c3
> --- /dev/null
> +++ b/docs/fusa/reqs/product-reqs/version_hypercall.rst
> @@ -0,0 +1,61 @@
> +.. SPDX-License-Identifier: CC-BY-4.0
> +
> +Version hypercall
> +=================
> +
> +First Parameter
> +---------------
> +
> +`XenProd~version_hyp_first_param~1`
> +
> +Description:
> +Xen shall treat the first argument (as an integer) to denote the command 
> number
> +for the hypercall.

You speak of argument here and parameter earlier.
I would rephrase to: the first argument of an hypercall exception as the 
command number for the hypercall.

> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenMkt~version_hypercall~1`
> +
> +Needs:
> + - XenSwdgn
> +
> +Second Parameter
> +----------------
> +
> +`XenProd~version_hyp_second_param~1`
> +
> +Description:
> +Xen shall treat the second argument as a virtual address to buffer in 
> domain's
> +memory.
> +

Same here on argument vs parameter.

> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenMkt~version_hypercall~1`
> +
> +Needs:
> + - XenSwdgn
> +
> +Return Value
> +------------
> +
> +`XenProd~version_hyp_ret_val~1`
> +
> +Description:
> +In case the hypercall fails, Xen shall return one of the error codes defined
> +in 
> http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

This is a very imprecise req as it does not states what can fail and what 
should be returned exactly.
Do we want to be that generic ? if yes then this might be a requirement valid 
for any hypercall.

Cheers
Bertrand

> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenMkt~version_hypercall~1`
> +
> +Needs:
> + - XenSwdgn
> \ No newline at end of file
> -- 
> 2.25.1
> 




 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.