Skip to contentSkip to conversation

docs: fusa: Define the requirements for XEN_VERSION hypercall.

PATCH Superseded Ayan Kumar Halder 3 participants 8 messages May 9, 2025 – Jul 17, 2025

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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
new file mode 100644
index 0000000000..f00b0b00f9
@@ -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
index 1088a51d52..d8683edce7 100644
@@ -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
index 2d297ecc13..0e29fe5362 100644
@@ -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
#1 lore raw

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
index f00b0b00f9..f58a9d50aa 100644
@@ -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
new file mode 100644
index 0000000000..3aa12ea2c2
@@ -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
index d8683edce7..de19b0cda2 100644
@@ -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
new file mode 100644
index 0000000000..b57b9acde8
@@ -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
#2 lore raw

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.

---
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 +0 -0
index f00b0b00f9..f58a9d50aa 100644
@@ -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
new file mode 100644
index 0000000000..3aa12ea2c2

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
new file mode 100644
index 0000000000..aac5896965

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
index d8683edce7..de19b0cda2 100644
@@ -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 +0 -0
new file mode 100644
index 0000000000..b57b9acde8

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:
+ - XenSwdgn
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index 400d51bbeb..2ef1c4f9ca 100644
@@ -41,3 +41,86 @@ Covers:
 

Needs:
- XenSwdgn

docs/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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#3 lore raw

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.

---
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 +0 -0
index f00b0b00f9..f58a9d50aa 100644
@@ -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
new file mode 100644
index 0000000000..3aa12ea2c2
@@ -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 -0
new file mode 100644
index 0000000000..aac5896965

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.

Quoted 3 lines

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.

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
index d8683edce7..de19b0cda2 100644
@@ -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 +3 -0
new file mode 100644
index 0000000000..b57b9acde8
@@ -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:
+ - XenSwdgn
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index 400d51bbeb..2ef1c4f9ca 100644
@@ -41,3 +41,86 @@ Covers:
 

Needs:
- XenSwdgn

docs/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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#4 lore raw

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.

---
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 +0 -0
index f00b0b00f9..f58a9d50aa 100644
@@ -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
new file mode 100644
index 0000000000..3aa12ea2c2
@@ -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 -0
new file mode 100644
index 0000000000..aac5896965

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.

Quoted 3 lines

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 5 lines

Should I say

Description:

Xen shall return its version when XENVER_version command 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_extraversion command 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
index d8683edce7..de19b0cda2 100644
@@ -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 +3 -0
new file mode 100644
index 0000000000..b57b9acde8
@@ -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:
+ - XenSwdgn
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index 400d51bbeb..2ef1c4f9ca 100644
@@ -41,3 +41,86 @@ Covers:
 

Needs:
- XenSwdgn

docs/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.

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 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.

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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#5 lore raw
In reply to Ayan Kumar Halder

Hi Ayan,

Quoted 33 lines · Ayan Kumar Halder

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 +2 -0
new file mode 100644
index 0000000000..f00b0b00f9
@@ -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
index 1088a51d52..d8683edce7 100644
@@ -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 +0 -0
index 2d297ecc13..0e29fe5362 100644
@@ -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:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +3 -0
new file mode 100644
index 0000000000..400d51bbeb
@@ -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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#6 lore raw
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_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 +2 -0
new file mode 100644
index 0000000000..f00b0b00f9
@@ -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 calls

So i would put the 0xEA1 value 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
index 1088a51d52..d8683edce7 100644
@@ -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 +0 -0
index 2d297ecc13..0e29fe5362 100644
@@ -79,3 +79,19 @@ Comments:
 
Quoted 12 lines

docs/fusa/reqs/market-reqs/reqs.rst Comments: · line 90

Quoted 11 lines

Needs:
- XenProd

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

Ack

Quoted 20 lines
Quoted 20 lines
docs/fusa/reqs/market-reqs/reqs.rst +7 -0
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
new file mode 100644
index 0000000000..400d51bbeb
@@ -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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#7 lore raw

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_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 +2 -0
new file mode 100644
index 0000000000..f00b0b00f9
@@ -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 calls

So i would put the 0xEA1 value 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 be 0xEA1.
ESR_EL2.EC should be 0x16.

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`
+
+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
index 1088a51d52..d8683edce7 100644
@@ -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 +0 -0
index 2d297ecc13..0e29fe5362 100644
@@ -79,3 +79,19 @@ Comments:
 
Quoted 12 lines

docs/fusa/reqs/market-reqs/reqs.rst Comments: · line 90

Quoted 11 lines

Needs:
- XenProd

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

Ack

Quoted 20 lines
Quoted 20 lines
docs/fusa/reqs/market-reqs/reqs.rst +7 -0
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
new file mode 100644
index 0000000000..400d51bbeb
@@ -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.

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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand