docs: fusa: Define the requirements for XEN_VERSION hypercall.
PATCH v2 1/2 docs: fusa: Define the requirements for XEN_VERSION hypercall.
In the current patch, we have defined the requirements which are common for all the commands.
---
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
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
@@ -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`
docs/fusa/reqs/index.rst +2 -0
@@ -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
docs/fusa/reqs/market-reqs/reqs.rst +16 -0
@@ -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
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +61 -0
62 lines not on this page · raw message
Signature · 1 line
2.25.1
PATCH v2 2/2 docs: fusa: Add the requirements for some of the commands of XEN_VERSION
We have written the requirements for some of the commands of the XEN_VERSION hypercall.
---
Changes from -
v1 - 1. Reworded the requirement so as to avoid mentioining variable names or hardcoded strings. Otherwise, one would need to change the requirement each time the code changes.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 6 +- .../design-reqs/arm64/version_hypercall.rst | 34 ++++++++ .../reqs/design-reqs/version_hypercall.rst | 65 +++++++++++++++ docs/fusa/reqs/index.rst | 2 + .../reqs/product-reqs/version_hypercall.rst | 83 +++++++++++++++++++ 5 files changed, 187 insertions(+), 3 deletions(-) create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +3 -3
@@ -28,8 +28,8 @@ 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. +Xen shall use the first register to read the first parameter, second register +for second parameter and so on, for domain hypercall requests. Rationale:
@@ -45,7 +45,7 @@ Return value `XenSwdgn~arm64_ret_val~1` Description: -Xen shall store the return value in x0 register. +Xen shall store the return value in first register. Rationale:
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +34 -0
@@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Capabilities +------------ + +`XenSwdgn~arm64_capabilities~1` + +Description: +Xen shall have an internal constant string to denote that the cpu is running +in arm64 mode. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_capabilities_cmd~1` + +Capabilities AArch32 +-------------------- + +`XenSwdgn~arm64_capabilities_aarch32~1` + +Description: +Xen shall have a internal constant string to denote that the cpu is running in +arm32 mode. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_capabilities_cmd~1` +
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +65 -0
65 lines not on this page · raw message
docs/fusa/reqs/index.rst +2 -0
@@ -14,3 +14,5 @@ Requirements documentation design-reqs/arm64/generic-timer design-reqs/arm64/sbsa-uart design-reqs/arm64/hypercall + design-reqs/arm64/version_hypercall + design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst +83 -0
89 lines not on this page · raw message
Signature · 1 line
2.25.1
Re: [PATCH v2 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION
Hi Ayan,
Quoted 41 lines · Ayan Kumar Halder
We have written the requirements for some of the commands of the
XEN_VERSIONhypercall.Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Reworded the requirement so as to avoid mentioining variable names or hardcoded strings. Otherwise, one would need to change the requirement each time the code changes.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 6 +- .../design-reqs/arm64/version_hypercall.rst | 34 ++++++++ .../reqs/design-reqs/version_hypercall.rst | 65 +++++++++++++++ docs/fusa/reqs/index.rst | 2 + .../reqs/product-reqs/version_hypercall.rst | 83 +++++++++++++++++++ 5 files changed, 187 insertions(+), 3 deletions(-)create mode 100644
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rstcreate mode 100644docs/fusa/reqs/design-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst +0
-0@@ -28,8 +28,8 @@ Parameters
XenSwdgn~arm64_hyp_param~1Description:
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +2
-2-Xen shall use x0 to read the first parameter, x1 for second parameter and so -on, for domain hypercall requests. +Xen shall use the first register to read the first parameter, second register +for second parameter and so on, for domain hypercall requests.Rationale:
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +0
-0@@ -45,7 +45,7 @@ Return value
XenSwdgn~arm64_ret_val~1Description:
docs/fusa/reqs/design-reqs/arm64/hypercall.rst Return value · line 48
Quoted 2 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +1
-1-Xen shall store the return value in x0 register. +Xen shall store the return value in first register.
It seems that those changes should be in the previous patch directly.
With that fixed:
Cheers
Bertrand
Quoted 221 lines
Rationale:
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +34
-0@@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Capabilities +------------ + +`XenSwdgn~arm64_capabilities~1` + +Description: +Xen shall have an internal constant string to denote that the cpu is running +in arm64 mode. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_capabilities_cmd~1` + +Capabilities AArch32 +-------------------- + +`XenSwdgn~arm64_capabilities_aarch32~1` + +Description: +Xen shall have a internal constant string to denote that the cpu is running in +arm32 mode. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_capabilities_cmd~1` +docs/fusa/reqs/design-reqs/version_hypercall.rst new file +65
-0@@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version +------- + +`XenSwdgn~version~1` + +Description: +Xen shall have a internal constant (XEN_VERSION) storing the version number +coming from the Makefile. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_version_cmd~1` + +Subversion +---------- + +`XenSwdgn~subversion~1` + +Description: +Xen shall have a internal constant (XEN_SUBVERSION) storing the sub version +number coming from the Makefile. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_version_cmd~1` + +Extraversion +------------ + +`XenSwdgn~extraversion~1` + +Description: +Xen shall have a internal constant (XEN_EXTRAVERSION) storing the extraversion +coming from the build environment. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_extraversion_cmd~1` + +Changeset +--------- + +`XenSwdgn~changeset~1` + +Description: +Xen shall have a internal constant string (XEN_CHANGESET) storing the date, +time and git hash of the last change made to Xen's codebase. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_changeset_cmd~1`docs/fusa/reqs/index.rst +2
-0@@ -14,3 +14,5 @@ Requirements documentation design-reqs/arm64/generic-timer design-reqs/arm64/sbsa-uart design-reqs/arm64/hypercall + design-reqs/arm64/version_hypercall + design-reqs/version_hypercalldocs/fusa/reqs/product-reqs/version_hypercall.rst +0
-0@@ -54,6 +54,89 @@ Rationale:Comments:
docs/fusa/reqs/product-reqs/version_hypercall.rst +83
-0+Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Version command +--------------- + +`XenProd~version_hyp_version_cmd~1` + +Description: +Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen's +version in the domain's register 0. + +Rationale: + +Comments: +Xen version is composed of major and minor number. + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Extraversion command +-------------------- + +`XenProd~version_hyp_extraversion_cmd~1` + +Description: +Xen shall provide a command (num 1) for hypercall (num 17) to copy its +extraversion in the domain's buffer. + +Rationale: + +Comments: +Xen's extra version consists of a string passed with 'XEN_VENDORVERSION' command +line parameter while building Xen. + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Capabilities command +-------------------- + +`XenProd~version_hyp_capabilities_cmd~1` + +Description: +Xen shall provide a command (num 3) for hypercall (num 17) to copy its +capabilities to the domain's buffer. + +Rationale: + +Comments: +Capabilities related information is represented by char[1024]. +For Arm64, the capabilities should contain "xen-3.0-aarch64" string. + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Changeset command +----------------- + +`XenProd~version_hyp_changeset_cmd~1` + +Description: +Xen shall provide a command (num 4) for hypercall (num 17) to copy changeset +to the domain's buffer. + +Rationale: + +Comments: +Changeset is string denoting the date, time and git hash of the last change +made to Xen's codebase. +Covers:
-XenMkt~version_hypercall~1Signature · 1 line
2.25.1
Hi Ayan,
Quoted 128 lines · Ayan Kumar Halder
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55
-0@@ -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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +0
-0@@ -79,3 +79,19 @@ Comments:Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +16
-0+ +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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +3
-0@@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst line 13
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+================= + +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.
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn
docs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +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.
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +8
-0+Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs:
docs/fusa/reqs/product-reqs/version_hypercall.rst line 51
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ - 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
Quoted 14 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
I have just some clarifications.
Quoted 133 lines
Quoted 133 lines · Ayan Kumar Halder
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55
-0@@ -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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +0
-0@@ -79,3 +79,19 @@ Comments:Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +16
-0+ +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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-0@@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall +================= + +First Parameter +---------------
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 13
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`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.
Ack
Should I do this everywhere ?
s/parameter/argument
That would make it consistent.
Quoted 35 lines
Quoted 11 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +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.
Quoted 12 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +12
-0+Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Return Value +------------
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 51
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`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.
Yes, you are correct.
I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.
IOW, we don't need to validate each and every error code returned by the hypercall.
Or should we just drop this requirement ?
- Ayan
Quoted 18 lines
Cheers
BertrandQuoted 14 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Hi Ayan,
Quoted 152 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
I have just some clarifications.
Quoted 133 lines
Quoted 133 lines · Ayan Kumar Halder
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55
-0@@ -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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +0
-0@@ -79,3 +79,19 @@ Comments:Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +16
-0+ +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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-0@@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall +================= + +First Parameter +---------------Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 13
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`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.
Quoted 7 lines
Ack
Should I do this everywhere ?
s/parameter/argument
That would make it consistent.
Yes definitely
Quoted 45 lines
Quoted 36 lines
Quoted 12 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +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.
Quoted 12 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +12
-0+Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Return Value +------------Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 51
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`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.
Quoted 7 lines
Yes, you are correct.
I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.
IOW, we don't need to validate each and every error code returned by the hypercall.
Or should we just drop this requirement ?
I think you should move this requirement and make it a generic one valid for all hypercalls.
Now at some point you might have to describe which error is caused by what problem as part of your hypercall interface definition.
ie: one generic product req and per hypercall design req describing the error cases.
At the end you should have a test to trigger each error condition and that test will be linked to the design req corresponding.
Cheers
Bertrand
Quoted 20 lines
- Ayan
Quoted 17 lines
Cheers
BertrandQuoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
Quoted 201 lines
Quoted 150 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
I have just some clarifications.
Quoted 132 lines
Quoted 132 lines · Ayan Kumar Halder
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55
-0@@ -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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +0
-0@@ -79,3 +79,19 @@ Comments:Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +16
-0+ +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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-0@@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall +================= + +First Parameter +---------------Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 13
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`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.Quoted 7 lines
Ack
Should I do this everywhere ?
s/parameter/argument
That would make it consistent.
Yes definitely
Quoted 42 lines
Quoted 42 lines
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +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.
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +8
-0+Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs:docs/fusa/reqs/product-reqs/version_hypercall.rst line 51
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ - 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.
Quoted 8 lines
Quoted 7 lines
Yes, you are correct.
I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.
IOW, we don't need to validate each and every error code returned by the hypercall.
Or should we just drop this requirement ?
I think you should move this requirement and make it a generic one valid for all hypercalls.
Yes, I will place it under hypercall.rst.
Quoted 3 lines
Now at some point you might have to describe which error is caused by what problem as part of your hypercall interface definition.
ie: one generic product req and per hypercall design req describing the error cases.
Agreed.
And an example design requirement which will be linked is :-
Xen shall return -EFAULT if it encounters an error while copying the extraversion string to domain's buffer.
Is this what you have in mind ?
Quoted 2 lines
At the end you should have a test to trigger each error condition and that test will be linked to the design req corresponding.
Ack.
- Ayan
Quoted 23 lines
Cheers
BertrandQuoted 18 lines
- Ayan
Quoted 16 lines
Cheers
BertrandQuoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Hi Ayan,
Quoted 220 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
Quoted 201 lines
Quoted 150 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
I have just some clarifications.
Quoted 132 lines
Quoted 132 lines · Ayan Kumar Halder
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55
-0@@ -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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +0
-0@@ -79,3 +79,19 @@ Comments:Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +16
-0+ +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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-0@@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall +================= + +First Parameter +---------------Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 13
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`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.Quoted 7 lines
Ack
Should I do this everywhere ?
s/parameter/argument
That would make it consistent.
Yes definitely
Quoted 42 lines
Quoted 42 lines
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +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.
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +8
-0+Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs:docs/fusa/reqs/product-reqs/version_hypercall.rst line 51
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ - 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.
Quoted 8 lines
Quoted 7 lines
Yes, you are correct.
I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.
IOW, we don't need to validate each and every error code returned by the hypercall.
Or should we just drop this requirement ?
I think you should move this requirement and make it a generic one valid for all hypercalls.
Yes, I will place it under
hypercall.rst.Quoted 3 lines
Now at some point you might have to describe which error is caused by what problem as part of your hypercall interface definition.
ie: one generic product req and per hypercall design req describing the error cases.
Quoted 7 lines
Agreed.
And an example design requirement which will be linked is :-
Xen shall return
-EFAULTif it encounters an error while copying the extraversion string to domain's buffer.Is this what you have in mind ?
Yes it is.
But is it the only error that can be return by the hypercall ?
Bertrand
Quoted 30 lines
Quoted 3 lines
At the end you should have a test to trigger each error condition and that test will be linked to the design req corresponding.
Ack.
- Ayan
Quoted 22 lines
Cheers
BertrandQuoted 18 lines
- Ayan
Quoted 16 lines
Cheers
BertrandQuoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Hi,
Quoted 35 lines · Ayan Kumar Halder
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +9
-0@@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Hypercall +========= + +Instruction +----------- + +`XenSwdgn~arm64_hyp_instr~1`
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 19
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10
-0+ +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.
Are you trying to describe any hypercalls (e.g. SMCCC, Xen...) or just the Xen one? If the latter, only "hvc #0xEA1" will be used for Xen hypercalls. Other immediate/space will be used for something different (i.e. #0 is used for SMCCC).
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 32
Quoted 12 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +12
-0+> +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.
This implies we are supporting a large number of parameters. However, Xen is only support 5 arguments. So I would just list all the registers.
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 24
Quoted 9 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +9
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` +
You don't seem to describe how the hypercall number is passed. Is this intended?
Quoted 78 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14
-0+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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +16
-0@@ -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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +22
-0@@ -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. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs:
docs/fusa/reqs/product-reqs/version_hypercall.rst line 32
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ - 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.
We don't support any VA. The VA will need to be mapped with specifc attributes (see include/public/arch-arm.h). Should this be mentioned in the requirement?
Quoted 30 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29
-0+ +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. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn
Signature · 1 line
Julien Grall
Quoted 1 line · Julien Grall
Hi,
Hi Julien/Bertrand,
Quoted 42 lines · Ayan Kumar Halder
Quoted 40 lines
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14
-0@@ -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:
Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 19
Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +3
-0+ +Comments: +Hypercall is one of the communication mechanism between Xen anddomains.
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +2
-0+Domains use hypercalls for various requests to Xen. +Domains use 'hvc' instruction to invoke hypercalls.Are you trying to describe any hypercalls (e.g. SMCCC, Xen...) or just the Xen one? If the latter, only "hvc #0xEA1" will be used for Xen hypercalls. Other immediate/space will be used for something different (i.e. #0 is used for SMCCC).
Yes, only the Xen one. I will mention "hvc #0xEA1".
Quoted 16 lines
Quoted 12 lines
+> +Covers:
+ -XenProd~version_hyp_first_param~1
+ -XenProd~version_hyp_second_param~1docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +8
-0+ +Parameters +---------- + +`XenSwdgn~arm64_hyp_param~1` + +Description: +Xen shall use x0 to read the first parameter, x1 for secondQuoted 2 lines
parameter and so
+on, for domain hypercall requests.This implies we are supporting a large number of parameters. However, Xen is only support 5 arguments. So I would just list all the registers.
Xen shall use the first five cpu core registers to obtain the arguments for domain hypercall requests. Xen shall read the first register for the first argument, second register for the second argument and so on.
@Bertrand :- Does this look ok to you ? I deliberately changed from x0 to first register so that this can be valid for both arm64 and arm32. Please comment.
Quoted 12 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 24
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +9
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` +You don't seem to describe how the hypercall number is passed. Is this intended?
Good catch. I will add a requirement.
Xen shall read x16 to obtain the hypercall number.
Xen shall read r12 to obtain the hypercall number.
Quoted 85 lines
Quoted 85 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14
-0+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`docs/fusa/reqs/index.rst +0
-0@@ -10,5 +10,7 @@ Requirements documentationmarket-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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +0
-0@@ -79,3 +79,19 @@ Comments:Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +8
-0+ +Version hypercall +----------------- + +`XenMkt~version_hypercall~1` + +Description: +Xen shall provide an interface for the domains to retrieve Xen'sversion, type
docs/fusa/reqs/market-reqs/reqs.rst +8
-0+and compilation information. + +Rationale: + +Comments: + +Needs: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +12
-0@@ -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 thecommand number
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +15
-0+for the hypercall. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Second Parameter +---------------- +
Quoted 8 lines
Quoted 6 lines
+
XenProd~version_hyp_second_param~1docs/fusa/reqs/product-reqs/version_hypercall.rst new file +3
-0+ +Description: +Xen shall treat the second argument as a virtual address to bufferin domain's
+memory.We don't support any VA. The VA will need to be mapped with specifc attributes (see
include/public/arch-arm.h). Should this be mentioned in the requirement?
....as a virtual address (mapped as Normal Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's ....
- Ayan
Quoted 34 lines
Quoted 33 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +18
-0+ +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 codesdefined
+in
http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn
Hi Ayan,
Quoted 72 lines · Ayan Kumar Halder
Quoted 1 line · Julien Grall
Hi,
Hi Julien/Bertrand,
Quoted 41 lines · Ayan Kumar Halder
Quoted 39 lines
In the current patch, we have defined the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>---
Changes from -v1 - 1. Fixed
XenProd~version_hyp_ret_val~1requirement 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.rstcreate mode 100644docs/fusa/reqs/product-reqs/version_hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +13
-0@@ -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. +Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 19
Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +6
-0+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.Are you trying to describe any hypercalls (e.g. SMCCC, Xen...) or just the Xen one? If the latter, only "hvc #0xEA1" will be used for Xen hypercalls. Other immediate/space will be used for something different (i.e. #0 is used for SMCCC).
Yes, only the Xen one. I will mention "hvc #0xEA1".
Quoted 15 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 32
Quoted 13 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +12
-0+> +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.This implies we are supporting a large number of parameters. However, Xen is only support 5 arguments. So I would just list all the registers.
Quoted 3 lines
Xen shall use the first five cpu core registers to obtain the arguments for domain hypercall requests. Xen shall read the first register for the first argument, second register for the second argument and so on.
@Bertrand :- Does this look ok to you ? I deliberately changed from x0 to first register so that this can be valid for both arm64 and arm32. Please comment.
Yes we should mention the 5 registers as those are the one supported by Xen and also the register where the hypercall number is passed as mentioned after
Cheers
Bertrand
Quoted 146 lines
Quoted 13 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 24
Quoted 11 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +9
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` +You don't seem to describe how the hypercall number is passed. Is this intended?
Good catch. I will add a requirement.
Xen shall read x16 to obtain the hypercall number.
Xen shall read r12 to obtain the hypercall number.
Quoted 82 lines
Quoted 82 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14
-0+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`docs/fusa/reqs/index.rst +2
-0@@ -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/hypercalldocs/fusa/reqs/market-reqs/reqs.rst +16
-0@@ -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: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +26
-0@@ -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. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Second Parameter +----------------Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 32
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0+ +`XenProd~version_hyp_second_param~1` + +Description: +Xen shall treat the second argument as a virtual address to buffer in domain's +memory.We don't support any VA. The VA will need to be mapped with specifc attributes (see
include/public/arch-arm.h). Should this be mentioned in the requirement?....as a virtual address (mapped as Normal Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's ....
- Ayan
Quoted 31 lines
Quoted 31 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29
-0+ +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. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn