docs: fusa: Define the requirements for XEN_VERSION hypercall.
PATCH v4 2/2 docs: fusa: Add the requirements for some of the commands of XEN_VERSION
In reply to Ayan Kumar HalderWe 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.
v2 - 1. Moved few changes to previous patch.
v3 - 1. Removed the internal implementation details from the design requirements so that they can be verified by black box tests.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++ .../design-reqs/arm64/version_hypercall.rst | 32 +++++++ .../reqs/design-reqs/version_hypercall.rst | 63 ++++++++++++++ docs/fusa/reqs/index.rst | 3 + docs/fusa/reqs/product-reqs/hypercall.rst | 20 +++++ .../reqs/product-reqs/version_hypercall.rst | 85 +++++++++++++++++++ 6 files changed, 218 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
@@ -58,3 +58,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 x0. + +Rationale: + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~1`
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +32 -0
@@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Capabilities +------------ + +`XenSwdgn~arm64_capabilities~1` + +Description: +Xen shall return xen-3.0-aarch64 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 return xen-3.0-armv7l 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 +63 -0
63 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 any 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 +85 -0
88 lines not on this page · raw message
Signature · 1 line
2.25.1
PATCH v4 1/2 docs: fusa: Define the requirements for XEN_VERSION hypercall.
Define 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).
v2 - 1. Specified the register details.
2. Specified the type of buffer.
v3 - Fixed some wordings to make it precise (eg register details, bit fields).
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 60 +++++++++++++++++++ docs/fusa/reqs/index.rst | 2 + docs/fusa/reqs/market-reqs/reqs.rst | 16 +++++ .../reqs/product-reqs/version_hypercall.rst | 42 +++++++++++++ 4 files changed, 120 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 +60 -0
@@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Hypercall +========= + +Instruction +----------- + +`XenSwdgn~arm64_hyp_instr~1` + +Description: +Xen shall treat domain hvc instruction execution (with 0xEA1) as hypercall +requests. + +Rationale: + +Comments: +Hypercall is one of the communication mechanism between Xen and domains. +Domains use hypercalls for various requests to Xen. +The exception syndrome register should have the following values :- +ESR_EL2.ISS should be 0xEA1. +ESR_EL2.EC should be 0x16. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Parameters +---------- + +`XenSwdgn~arm64_hyp_param~1` + +Description: +Xen shall use x0 - x4 core registers to obtain the arguments for domain hypercall +requests. + +Rationale: + +Comments: +Xen shall read x0 for the first argument, x1 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 a hypercall 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 +42 -0
42 lines not on this page · raw message
Signature · 1 line
2.25.1
Re: [PATCH v4 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION
In reply to Ayan Kumar HalderHi Ayan,
Quoted 6 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]>
Looks good to me.
Cheers
Bertrand
Quoted 289 lines
---
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.
v3 - 1. Removed the internal implementation details from the design requirements so that they can be verified by black box tests.
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++ .../design-reqs/arm64/version_hypercall.rst | 32 +++++++ .../reqs/design-reqs/version_hypercall.rst | 63 ++++++++++++++ docs/fusa/reqs/index.rst | 3 + docs/fusa/reqs/product-reqs/hypercall.rst | 20 +++++ .../reqs/product-reqs/version_hypercall.rst | 85 +++++++++++++++++++ 6 files changed, 218 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@@ -58,3 +58,18 @@ Comments:Covers:
-XenProd~version_hyp_first_param~1
-XenProd~version_hyp_second_param~1docs/fusa/reqs/design-reqs/arm64/hypercall.rst +15
-0+ +Return value +------------ + +`XenSwdgn~arm64_ret_val~1` + +Description: +Xen shall store the return value in x0. + +Rationale: + +Comments: + +Covers: + - `XenProd~hyp_err_ret_val~1`docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +32
-0@@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Capabilities +------------ + +`XenSwdgn~arm64_capabilities~1` + +Description: +Xen shall return xen-3.0-aarch64 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 return xen-3.0-armv7l 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 +63
-0@@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version +------- + +`XenSwdgn~version~1` + +Description: +Xen shall return its version when XENVER_version command is invoked. + +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 return its extraversion when XENVER_extraversion command is invoked. + +Rationale: + +Comments: + +Covers: + - `XenProd~version_hyp_extraversion_cmd~1` + +Changeset +--------- + +`XenSwdgn~changeset~1` + +Description: +Xen shall return its changeset when XENVER_changeset command is invoked. + +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 +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 any 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: + - XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +0
-0@@ -40,3 +40,88 @@ Covers:Needs:
- XenSwdgndocs/fusa/reqs/product-reqs/version_hypercall.rst +85
-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 +version in the domain's register 0. + +Rationale: + +Comments: +Xen version is composed of major (ie version) and minor (ie subversion) number. +The minor number is encoded in the 16 least significant bits and the major number +is encoded in the top remaining bits. + +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~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1
Hi Ayan,
Quoted 5 lines · Ayan Kumar Halder
Define the requirements which are common for all the commands.
Signed-off-by Ayan Kumar Halder <[email protected]>
Looks good
Cheers
Bertrand
Quoted 174 lines
---
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.v3 - Fixed some wordings to make it precise (eg register details, bit fields).
.../fusa/reqs/design-reqs/arm64/hypercall.rst | 60 +++++++++++++++++++ docs/fusa/reqs/index.rst | 2 + docs/fusa/reqs/market-reqs/reqs.rst | 16 +++++ .../reqs/product-reqs/version_hypercall.rst | 42 +++++++++++++ 4 files changed, 120 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 +60
-0@@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Hypercall +========= + +Instruction +----------- + +`XenSwdgn~arm64_hyp_instr~1` + +Description: +Xen shall treat domain hvc instruction execution (with 0xEA1) as hypercall +requests. + +Rationale: + +Comments: +Hypercall is one of the communication mechanism between Xen and domains. +Domains use hypercalls for various requests to Xen. +The exception syndrome register should have the following values :- +ESR_EL2.ISS should be 0xEA1. +ESR_EL2.EC should be 0x16. + +Covers: + - `XenProd~version_hyp_first_param~1` + - `XenProd~version_hyp_second_param~1` + +Parameters +---------- + +`XenSwdgn~arm64_hyp_param~1` + +Description: +Xen shall use x0 - x4 core registers to obtain the arguments for domain hypercall +requests. + +Rationale: + +Comments: +Xen shall read x0 for the first argument, x1 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:
- XenProddocs/fusa/reqs/market-reqs/reqs.rst +16
-0+ +Version hypercall +----------------- + +`XenMkt~version_hypercall~1` + +Description: +Xen shall provide a hypercall 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 +42
-0@@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Version hypercall +================= + +First Parameter +--------------- + +`XenProd~version_hyp_first_param~1` + +Description: +Xen shall treat the value stored in x0 as the command number for the hypercall. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgn + +Second Parameter +---------------- + +`XenProd~version_hyp_second_param~1` + +Description: +Xen shall treat the value stored in x1 as a domain virtual address (mapped as +Normal Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's +memory. + +Rationale: + +Comments: + +Covers: + - `XenMkt~version_hypercall~1` + +Needs: + - XenSwdgnSignature · 1 line
2.25.1