docs: fusa: Define the requirements for XEN_VERSION hypercall.
PATCH v3 1/2 docs: fusa: Define the requirements for XEN_VERSION hypercall.
Define the requirements which are common for all the commands for XEN_VERSION hypercall.
---
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).
v2 - 1. Specified the register details.
2. Specified the type of buffer.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 58 +++++++++++++++++++ docs/fusa/reqs/index.rst | 2 + docs/fusa/reqs/market-reqs/reqs.rst | 16 +++++ .../reqs/product-reqs/version_hypercall.rst | 43 ++++++++++++++ 4 files changed, 119 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 +58 -0
@@ -0,0 +1,58 @@ +.. 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 #0xEA1' 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 the first five cpu core registers to obtain the arguments for +domain hypercall requests. + +Rationale: + +Comments: +Xen shall read the first register for the first argument, second register for +the second argument and so on. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Hypercall number +---------------- + +`XenSwdgn~arm64_hyp_num~1` + +Description: +Xen shall read x16 to obtain the hypercall number. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~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 +43 -0
43 lines not on this page · raw message
Signature · 1 line
2.25.1
PATCH v3 2/2 docs: fusa: Add the requirements for few commands of XEN_VERSION
Define requirements for specific commands.
---
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.
v2 - 1. Moved few changes to previous patch.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++ .../design-reqs/arm64/version_hypercall.rst | 34 ++++++++ .../reqs/design-reqs/version_hypercall.rst | 82 ++++++++++++++++++ docs/fusa/reqs/index.rst | 3 + docs/fusa/reqs/product-reqs/hypercall.rst | 20 +++++ .../reqs/product-reqs/version_hypercall.rst | 83 +++++++++++++++++++ 6 files changed, 237 insertions(+) create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst create mode 100644 docs/fusa/reqs/product-reqs/hypercall.rst
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +15 -0
@@ -56,3 +56,18 @@ 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 first cpu core register. + +Rationale: + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~1`
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 +82 -0
82 lines not on this page · raw message
docs/fusa/reqs/index.rst +3 -0
@@ -11,6 +11,9 @@ Requirements documentation product-reqs/reqs product-reqs/arm64/reqs product-reqs/version_hypercall + product-reqs/hypercall 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/hypercall.rst new file +20 -0
@@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Error Return Value +------------------ + +`XenProd~hyp_err_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
docs/fusa/reqs/product-reqs/version_hypercall.rst +83 -0
86 lines not on this page · raw message
Signature · 1 line
2.25.1
Re: [PATCH v3 2/2] docs: fusa: Add the requirements for few commands of XEN_VERSION
Hi Ayan,
Quoted 33 lines · Ayan Kumar Halder
Define requirements for specific commands.
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.
v2 - 1. Moved few changes to previous patch.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++ .../design-reqs/arm64/version_hypercall.rst | 34 ++++++++ .../reqs/design-reqs/version_hypercall.rst | 82 ++++++++++++++++++ docs/fusa/reqs/index.rst | 3 + docs/fusa/reqs/product-reqs/hypercall.rst | 20 +++++ .../reqs/product-reqs/version_hypercall.rst | 83 +++++++++++++++++++ 6 files changed, 237 insertions(+)create mode 100644
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rstcreate mode 100644docs/fusa/reqs/design-reqs/version_hypercall.rstcreate mode 100644docs/fusa/reqs/product-reqs/hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst +0
-0@@ -56,3 +56,18 @@ Comments:Covers:
-XenProd~version_hyp_first_param~1
-XenProd~version_hyp_second_param~1
docs/fusa/reqs/design-reqs/arm64/hypercall.rst Comments: · line 66
Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +8
-0+ +Return value +------------ + +`XenSwdgn~arm64_ret_val~1` + +Description: +Xen shall store the return value in first cpu core register.
use x0 instead.
Quoted 13 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +7
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~1`docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +0
-0
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 10
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +10
-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.
This is untestable if this is purely internal so this cannot be a requirement I am not quite sure why you need this, can you explain ?
Quoted 30 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +24
-0+ +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 +0
-0
docs/fusa/reqs/design-reqs/version_hypercall.rst line 10
Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10
-0@@ -0,0 +1,82 @@ +.. 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.
I really have doubts about this and the following one.
If this only goal is to say what should be returned in the XEN_VERSION hypcall you might just need something saying it and mention this as a comment because you will have a very hard time to test such a requirement.
Quoted 92 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +72
-0+ +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` + +Error copying buffer +-------------------- + +`XenSwdgn~error_copy_buffer~1` + +Description: +Xen shall return -EFAULT if it is not able to copy data to domain's buffer. + +Rationale: +-EFAULT is one of the error code defined in +http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h. + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~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 +3
-0@@ -11,6 +11,9 @@ Requirements documentation product-reqs/reqs product-reqs/arm64/reqs product-reqs/version_hypercall + product-reqs/hypercall 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/hypercall.rst new file +0
-0
docs/fusa/reqs/product-reqs/hypercall.rst line 10
Quoted 10 lines
docs/fusa/reqs/product-reqs/hypercall.rst new file +10
-0@@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Error Return Value +------------------ + +`XenProd~hyp_err_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.
s/the/an/ hypercall otherwise it is not quite clear which hypercall you mean.
Quoted 22 lines
docs/fusa/reqs/product-reqs/hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +0
-0@@ -41,3 +41,86 @@ Covers:Needs:
- XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +4
-0+ +Version command +--------------- +
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 57
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +10
-0+`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.
How Xen version is encoded should be a requirement, you can add this directly into the definition of this one in fact i think.
Quoted 32 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +32
-0+ +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`
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 99
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +10
-0+ +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.
Isn't it mandatory for xen to return aarch64 for arm64 ? This could be turned into a requirement (easily testable).
Quoted 11 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +11
-0+ +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Changeset command +----------------- + +`XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 120
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +10
-0+ +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.
Does this has a standard format ? if so it should be explained.
Quoted 9 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+ +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Cheers
Bertrand
Re: [PATCH v3 2/2] docs: fusa: Add the requirements for few commands of XEN_VERSION
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
Quoted 35 lines
Quoted 35 lines · Ayan Kumar Halder
Define requirements for specific commands.
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.
v2 - 1. Moved few changes to previous patch.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++ .../design-reqs/arm64/version_hypercall.rst | 34 ++++++++ .../reqs/design-reqs/version_hypercall.rst | 82 ++++++++++++++++++ docs/fusa/reqs/index.rst | 3 + docs/fusa/reqs/product-reqs/hypercall.rst | 20 +++++ .../reqs/product-reqs/version_hypercall.rst | 83 +++++++++++++++++++ 6 files changed, 237 insertions(+)create mode 100644
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rstcreate mode 100644docs/fusa/reqs/design-reqs/version_hypercall.rstcreate mode 100644docs/fusa/reqs/product-reqs/hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst +0
-0@@ -56,3 +56,18 @@ Comments:Covers:
-XenProd~version_hyp_first_param~1
-XenProd~version_hyp_second_param~1
+
Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst Comments: · line 66
Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +7
-0+Return value +------------ + +`XenSwdgn~arm64_ret_val~1` + +Description: +Xen shall store the return value in first cpu core register.use x0 instead.
Ack
Quoted 18 lines
Quoted 18 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +7
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~1`docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +4
-0@@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Capabilities +------------
Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 10
Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +6
-0+ +`XenSwdgn~arm64_capabilities~1` + +Description: +Xen shall have an internal constant string to denote that the cpu is running +in arm64 mode.This is untestable if this is purely internal so this cannot be a requirement I am not quite sure why you need this, can you explain ?
We had agreed on this wording in "[PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION". You had mentioned this
``` All in all, the design just need to say that it must be stored somewhere "bounded" to the source code so that a tester can check it. ```
So, I infer that needs to be validated by code inspection. The string is set in init_xen_cap_info().
Quoted 43 lines
Quoted 31 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +24
-0+ +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 +0
-0docs/fusa/reqs/design-reqs/version_hypercall.rst line 10
Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10
-0@@ -0,0 +1,82 @@ +.. 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.I really have doubts about this and the following one.
Quoted 3 lines
If this only goal is to say what should be returned in the
XEN_VERSIONhypcall you might just need something saying it and mention this as a comment because you will have a very hard time to test such a requirement.
Should I say
Description:
Xen shall return its version when XENVER_version command is invoked.
If so , then ...
Quoted 17 lines
Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +6
-0+ +Rationale: + +Comments: + +Covers:docs/fusa/reqs/design-reqs/version_hypercall.rst line 26
Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10
-0+ - `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.
Xen shall return its extra version when XENVER_extraversion command is invoked.
Quoted 79 lines
Quoted 79 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +56
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_version_cmd~1` + +Error copying buffer +-------------------- + +`XenSwdgn~error_copy_buffer~1` + +Description: +Xen shall return -EFAULT if it is not able to copy data to domain's buffer. + +Rationale: +-EFAULT is one of the error code defined in +http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h. + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~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 +3
-0@@ -11,6 +11,9 @@ Requirements documentation product-reqs/reqs product-reqs/arm64/reqs product-reqs/version_hypercall + product-reqs/hypercall 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/hypercall.rst new file +3
-0@@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Error Return Value
Quoted 8 lines
docs/fusa/reqs/product-reqs/hypercall.rst line 10
Quoted 7 lines
docs/fusa/reqs/product-reqs/hypercall.rst new file +7
-0+------------------ + +`XenProd~hyp_err_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.s/the/an/ hypercall otherwise it is not quite clear which hypercall you mean.
Ack
Quoted 27 lines
Quoted 27 lines
docs/fusa/reqs/product-reqs/hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +0
-0@@ -41,3 +41,86 @@ Covers:Needs:
- XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +8
-0+ +Version command +--------------- + +`XenProd~version_hyp_version_cmd~1` + +Description: +Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen's
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 57
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+version in the domain's register 0. + +Rationale: + +Comments: +Xen version is composed of major and minor number.How Xen version is encoded should be a requirement, you can add this directly into the definition of this one in fact i think.
Do you mean the description should be :-
Description:
Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen's version (composed of major and minor number) in the domain's register 0.
Quoted 37 lines
Quoted 37 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +36
-0+ +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.
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 99
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+ +Rationale: + +Comments: +Capabilities related information is represented by char[1024]. +For Arm64, the capabilities should contain "xen-3.0-aarch64" string.Isn't it mandatory for xen to return aarch64 for arm64 ? This could be turned into a requirement (easily testable).
So should I change the following design requirement
"Xen shall have an internal constant string to denote that the cpu is running in arm64 mode."
to
"Xen shall return xen-3.0-aarch64 to denote that the cpu is running in arm64 mode."
Quoted 15 lines
Quoted 15 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +14
-0+ +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
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 120
Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +7
-0+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.Does this has a standard format ? if so it should be explained.
This is a implementation level detail. The format is autogenerated in compile.h
"Mon Dec 30 22:00:31 2024 +0100 git:0d729221ab"
How do you want me explain this ?
- Ayan
Quoted 14 lines
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+ +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1Cheers
Bertrand
Re: [PATCH v3 2/2] docs: fusa: Add the requirements for few commands of XEN_VERSION
Hi Ayan,
Sorry for the delay.
Quoted 79 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
Quoted 35 lines
Quoted 35 lines · Ayan Kumar Halder
Define requirements for specific commands.
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.
v2 - 1. Moved few changes to previous patch.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++ .../design-reqs/arm64/version_hypercall.rst | 34 ++++++++ .../reqs/design-reqs/version_hypercall.rst | 82 ++++++++++++++++++ docs/fusa/reqs/index.rst | 3 + docs/fusa/reqs/product-reqs/hypercall.rst | 20 +++++ .../reqs/product-reqs/version_hypercall.rst | 83 +++++++++++++++++++ 6 files changed, 237 insertions(+)create mode 100644
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rstcreate mode 100644docs/fusa/reqs/design-reqs/version_hypercall.rstcreate mode 100644docs/fusa/reqs/product-reqs/hypercall.rstdocs/fusa/reqs/design-reqs/arm64/hypercall.rst +0
-0@@ -56,3 +56,18 @@ Comments:Covers:
-XenProd~version_hyp_first_param~1
-XenProd~version_hyp_second_param~1
+Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst Comments: · line 66
Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +7
-0+Return value +------------ + +`XenSwdgn~arm64_ret_val~1` + +Description: +Xen shall store the return value in first cpu core register.use x0 instead.
Ack
Quoted 18 lines
Quoted 18 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +7
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~1`docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +4
-0@@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Capabilities +------------Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 10
Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +6
-0+ +`XenSwdgn~arm64_capabilities~1` + +Description: +Xen shall have an internal constant string to denote that the cpu is running +in arm64 mode.This is untestable if this is purely internal so this cannot be a requirement I am not quite sure why you need this, can you explain ?
We had agreed on this wording in "[PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of
XEN_VERSION". You had mentioned this
Quoted 7 lines
``` All in all, the design just need to say that it must be stored somewhere "bounded" to the source code so that a tester can check it. ```So, I infer that needs to be validated by code inspection. The string is set in
init_xen_cap_info().
ok at the end this might be tested by inspecting the image ro data section.
Quoted 48 lines
Quoted 44 lines
Quoted 32 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +24
-0+ +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 +0
-0docs/fusa/reqs/design-reqs/version_hypercall.rst line 10
Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10
-0@@ -0,0 +1,82 @@ +.. 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.I really have doubts about this and the following one.
Quoted 3 lines
If this only goal is to say what should be returned in the
XEN_VERSIONhypcall you might just need something saying it and mention this as a comment because you will have a very hard time to test such a requirement.
Quoted 5 lines
Should I say
Description:
Xen shall return its version when
XENVER_versioncommand is invoked.
yes that sounds better.
Quoted 13 lines
If so , then ...
Quoted 10 lines
Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +9
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_version_cmd~1` + +Subversion
Quoted 8 lines
Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst line 26
Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7
-0+---------- + +`XenSwdgn~subversion~1` + +Description: +Xen shall have a internal constant (XEN_SUBVERSION) storing the sub version +number coming from the Makefile.Xen shall return its extra version when
XENVER_extraversioncommand is invoked.
yes
Quoted 124 lines
Quoted 79 lines
Quoted 79 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +56
-0+ +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_version_cmd~1` + +Error copying buffer +-------------------- + +`XenSwdgn~error_copy_buffer~1` + +Description: +Xen shall return -EFAULT if it is not able to copy data to domain's buffer. + +Rationale: +-EFAULT is one of the error code defined in +http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h. + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~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 +3
-0@@ -11,6 +11,9 @@ Requirements documentation product-reqs/reqs product-reqs/arm64/reqs product-reqs/version_hypercall + product-reqs/hypercall 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/hypercall.rst new file +3
-0@@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Error Return ValueQuoted 8 lines
docs/fusa/reqs/product-reqs/hypercall.rst line 10
Quoted 7 lines
docs/fusa/reqs/product-reqs/hypercall.rst new file +7
-0+------------------ + +`XenProd~hyp_err_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.s/the/an/ hypercall otherwise it is not quite clear which hypercall you mean.
Ack
Quoted 27 lines
Quoted 27 lines
docs/fusa/reqs/product-reqs/hypercall.rst new file +10
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +0
-0@@ -41,3 +41,86 @@ Covers:Needs:
- XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +8
-0+ +Version command +--------------- + +`XenProd~version_hyp_version_cmd~1` + +Description: +Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen'sQuoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 57
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+version in the domain's register 0. + +Rationale: + +Comments: +Xen version is composed of major and minor number.How Xen version is encoded should be a requirement, you can add this directly into the definition of this one in fact i think.
Quoted 6 lines
Do you mean the description should be :-
Description:
Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen's version (composed of major and minor number) in the domain's register 0.
If you want to test that the version is what you expect you need to know how it is encoded. So might be something like major number in bits x to y, minor in xxx etc.
Quoted 47 lines
Quoted 38 lines
Quoted 38 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +36
-0+ +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.Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 99
Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+ +Rationale: + +Comments: +Capabilities related information is represented by char[1024]. +For Arm64, the capabilities should contain "xen-3.0-aarch64" string.Isn't it mandatory for xen to return aarch64 for arm64 ? This could be turned into a requirement (easily testable).
Quoted 7 lines
So should I change the following design requirement
"Xen shall have an internal constant string to denote that the cpu is running in arm64 mode."
to
"Xen shall return xen-3.0-aarch64 to denote that the cpu is running in arm64 mode."
yes
Quoted 25 lines
Quoted 16 lines
Quoted 16 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +14
-0+ +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 changesetQuoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 120
Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +7
-0+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.Does this has a standard format ? if so it should be explained.
Quoted 5 lines
This is a implementation level detail. The format is autogenerated in
compile.h"Mon Dec 30 22:00:31 2024 +0100 git:0d729221ab"
How do you want me explain this ?
No then the sentence is ok as is i would say.
Cheers
Bertrand
Quoted 15 lines
- Ayan
Quoted 12 lines
Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +6
-0+ +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1Cheers
Bertrand
Hi Ayan,
Quoted 33 lines · Ayan Kumar Halder
Define the requirements which are common for all the commands for
XEN_VERSIONhypercall.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).v2 - 1. Specified the register details.
2. Specified the type of buffer..../fusa/reqs/design-reqs/arm64/hypercall.rst | 58 +++++++++++++++++++ docs/fusa/reqs/index.rst | 2 + docs/fusa/reqs/market-reqs/reqs.rst | 16 +++++ .../reqs/product-reqs/version_hypercall.rst | 43 ++++++++++++++ 4 files changed, 119 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 +2
-0@@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: CC-BY-4.0 +
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 12
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10
-0+Hypercall +========= + +Instruction +----------- + +`XenSwdgn~arm64_hyp_instr~1` + +Description: +Xen shall treat domain hypercall exception as hypercall requests.
This really reads weirdly.
Maybe: Xen shall treat domain hvc instruction execution as hypercall requests.
Then you can add a comment to explain that this is detected through a specific exception.
Also this is not completely true as hvc is also used in other scenarios:
- PSCI calls
- Firmware calls
So i would put the 0xEA1 value as part of the requirement.
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10
-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 #0xEA1' instruction to invoke hypercalls. + +Covers: + - `XenProd~version_hyp_first_param~1`
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 32
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10
-0+ - `XenProd~version_hyp_second_param~1` + +Parameters +---------- + +`XenSwdgn~arm64_hyp_param~1` + +Description: +Xen shall use the first five cpu core registers to obtain the arguments for +domain hypercall requests.
Why not say x0 to x4 registers instead ? You use x16 after anyway
Quoted 46 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +26
-0+ +Rationale: + +Comments: +Xen shall read the first register for the first argument, second register for +the second argument and so on. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Hypercall number +---------------- + +`XenSwdgn~arm64_hyp_num~1` + +Description: +Xen shall read x16 to obtain the hypercall number. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~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:
- XenProd
docs/fusa/reqs/market-reqs/reqs.rst Comments: · line 90
Quoted 9 lines
docs/fusa/reqs/market-reqs/reqs.rst +9
-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.
I would say hypercall instead of interface here
Quoted 16 lines
docs/fusa/reqs/market-reqs/reqs.rst +7
-0+ +Rationale: + +Comments: + +Needs: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +3
-0@@ -0,0 +1,43 @@ +.. 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.
I would be more precise and say x0 value.
Also "integer" is unspecified, use a more specific type definition (32/64 bit signed/unsigned integer).
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 (mapped as Normal +Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's +memory.
You should say "guest virtual address" to be more precise.
Quoted 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
Cheers
Bertrand
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
Quoted 47 lines
Quoted 34 lines · Ayan Kumar Halder
Define the requirements which are common for all the commands for
XEN_VERSIONhypercall.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).v2 - 1. Specified the register details.
2. Specified the type of buffer..../fusa/reqs/design-reqs/arm64/hypercall.rst | 58 +++++++++++++++++++ docs/fusa/reqs/index.rst | 2 + docs/fusa/reqs/market-reqs/reqs.rst | 16 +++++ .../reqs/product-reqs/version_hypercall.rst | 43 ++++++++++++++ 4 files changed, 119 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 +2
-0@@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: CC-BY-4.0 +docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 12
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10
-0+Hypercall +========= + +Instruction +----------- + +`XenSwdgn~arm64_hyp_instr~1` + +Description: +Xen shall treat domain hypercall exception as hypercall requests.This really reads weirdly.
Maybe: Xen shall treat domain hvc instruction execution as hypercall requests.
Quoted 7 lines
Then you can add a comment to explain that this is detected through a specific exception.
Also this is not completely true as hvc is also used in other scenarios:
- PSCI calls
- Firmware callsSo i would put the
0xEA1value as part of the requirement.
Description:
Xen shall treat domain hvc instruction execution (with 0xEA1) as hypercall requests.
Comments:
The exception syndrome register should have the following values :- ESR_EL2.ISS should be 0xEA1.
ESR_EL2.EC should be 0x16.
Quoted 14 lines
Quoted 14 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +13
-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 #0xEA1' instruction to invoke hypercalls. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Parameters
Quoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 32
Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +7
-0+---------- + +`XenSwdgn~arm64_hyp_param~1` + +Description: +Xen shall use the first five cpu core registers to obtain the arguments for +domain hypercall requests.Why not say x0 to x4 registers instead ? You use x16 after anyway
Ack
Quoted 45 lines
Quoted 45 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +26
-0+ +Rationale: + +Comments: +Xen shall read the first register for the first argument, second register for +the second argument and so on. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Hypercall number +---------------- + +`XenSwdgn~arm64_hyp_num~1` + +Description: +Xen shall read x16 to obtain the hypercall number. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~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:
Quoted 12 lines
docs/fusa/reqs/market-reqs/reqs.rst Comments: · line 90
Quoted 11 lines
Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +9
-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.I would say hypercall instead of interface here
Ack
Quoted 20 lines
Quoted 20 lines
docs/fusa/reqs/market-reqs/reqs.rst +7
-0+ +Rationale: + +Comments: + +Needs: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0@@ -0,0 +1,43 @@ +.. 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 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-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.I would be more precise and say x0 value.
Ack
Quoted 2 lines
Also "integer" is unspecified, use a more specific type definition (32/64 bit signed/unsigned integer).
It is a signed integer. The size is not mentioned.
ret = do_xen_version((int)(a1), (XEN_GUEST_HANDLE_PARAM(void)){ _p(a2) });
Quoted 14 lines
Quoted 14 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +13
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Second Parameter +----------------
Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-0+ +`XenProd~version_hyp_second_param~1` + +Description: +Xen shall treat the second argument as a virtual address (mapped as Normal +Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's +memory.You should say "guest virtual address" to be more precise.
Ack
s/guest/domain
- Ayan
Quoted 17 lines
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.1Cheers
Bertrand
Hi Ayan,
Quoted 63 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis
Hi Ayan,
Hi Bertrand,
Quoted 47 lines
Quoted 34 lines · Ayan Kumar Halder
Define the requirements which are common for all the commands for
XEN_VERSIONhypercall.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).v2 - 1. Specified the register details.
2. Specified the type of buffer..../fusa/reqs/design-reqs/arm64/hypercall.rst | 58 +++++++++++++++++++ docs/fusa/reqs/index.rst | 2 + docs/fusa/reqs/market-reqs/reqs.rst | 16 +++++ .../reqs/product-reqs/version_hypercall.rst | 43 ++++++++++++++ 4 files changed, 119 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 +2
-0@@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: CC-BY-4.0 +docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 12
Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10
-0+Hypercall +========= + +Instruction +----------- + +`XenSwdgn~arm64_hyp_instr~1` + +Description: +Xen shall treat domain hypercall exception as hypercall requests.This really reads weirdly.
Maybe: Xen shall treat domain hvc instruction execution as hypercall requests.Quoted 7 lines
Then you can add a comment to explain that this is detected through a specific exception.
Also this is not completely true as hvc is also used in other scenarios:
- PSCI calls
- Firmware callsSo i would put the
0xEA1value as part of the requirement.
Quoted 8 lines
Description:
Xen shall treat domain hvc instruction execution (with
0xEA1) as hypercall requests.Comments:
The exception syndrome register should have the following values :- ESR_EL2.ISS should be0xEA1.
ESR_EL2.EC should be0x16.
yes a lot better :-)
Quoted 110 lines
Quoted 15 lines
Quoted 15 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +13
-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 #0xEA1' instruction to invoke hypercalls. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +ParametersQuoted 8 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 32
Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +7
-0+---------- + +`XenSwdgn~arm64_hyp_param~1` + +Description: +Xen shall use the first five cpu core registers to obtain the arguments for +domain hypercall requests.Why not say x0 to x4 registers instead ? You use x16 after anyway
Ack
Quoted 45 lines
Quoted 45 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +26
-0+ +Rationale: + +Comments: +Xen shall read the first register for the first argument, second register for +the second argument and so on. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Hypercall number +---------------- + +`XenSwdgn~arm64_hyp_num~1` + +Description: +Xen shall read x16 to obtain the hypercall number. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~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:Quoted 12 lines
docs/fusa/reqs/market-reqs/reqs.rst Comments: · line 90
Quoted 11 lines
Needs:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +9
-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.I would say hypercall instead of interface here
Ack
Quoted 20 lines
Quoted 20 lines
docs/fusa/reqs/market-reqs/reqs.rst +7
-0+ +Rationale: + +Comments: + +Needs: + - XenProddocs/fusa/reqs/product-reqs/version_hypercall.rst new file +6
-0@@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall +================= + +First ParameterQuoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 13
Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-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.I would be more precise and say x0 value.
Quoted 7 lines
Ack
Quoted 2 lines
Also "integer" is unspecified, use a more specific type definition (32/64 bit signed/unsigned integer).
It is a signed integer. The size is not mentioned.
ret =
do_xen_version((int)(a1), (XEN_GUEST_HANDLE_PARAM(void)){ _p(a2) });
This is compiler dependent and architecture dependent so sounds weird. I would expect this to be int32_t.
Maybe something to check here.
Quoted 24 lines
Quoted 15 lines
Quoted 15 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +13
-0+ +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Second Parameter +----------------Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst line 33
Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7
-0+ +`XenProd~version_hyp_second_param~1` + +Description: +Xen shall treat the second argument as a virtual address (mapped as Normal +Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's +memory.You should say "guest virtual address" to be more precise.
Quoted 4 lines
Ack
s/guest/domain
yes
Cheers
Bertrand
Quoted 18 lines
- Ayan
Quoted 16 lines
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.1Cheers
Bertrand