Skip to contentSkip to conversation

docs: fusa: Define the requirements for XEN_VERSION hypercall.

PATCH Superseded Ayan Kumar Halder 5 participants 14 messages Jan 14, 2025 – Feb 24, 2025

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 docs: fusa: Define the requirements for XEN_VERSION hypercall.

In the current patch, we have defined the requirements which are common for all the commands.

---
 .../fusa/reqs/design-reqs/arm64/hypercall.rst | 52 ++++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
 .../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
 4 files changed, 131 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 +52 -0
new file mode 100644
index 0000000000..66dbcc3026
@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Domains shall use the Arm instruction 'hvc' to interact with Xen.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Domains shall use register x0 to pass first parameter, x1 to pass second
+parameter and so on.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +61 -0

61 lines not on this page · raw message

Signature · 1 line
2.25.1
#1 lore raw

PATCH 2/2 docs: fusa: Add the requirements for some of the commands of XEN_VERSION

We have written the requirements for some of the commands of the XEN_VERSION hypercall.

---
 .../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
 .../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 .../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
 4 files changed, 182 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +33 -0
new file mode 100644
index 0000000000..1dad2b84c2
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
+Capabilities AArch32
+--------------------
+
+`XenSwdgn~arm64_capabilities_aarch32~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-armv7l" when it
+detects that the cpu is running in AArch32 mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +65 -0

65 lines not on this page · raw message

docs/fusa/reqs/index.rst +2 -0
index d8683edce7..b85af19d19 100644
@@ -14,3 +14,5 @@ Requirements documentation
    design-reqs/arm64/generic-timer
    design-reqs/arm64/sbsa-uart
    design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst +82 -0

85 lines not on this page · raw message

Signature · 1 line
2.25.1
#2 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

Hi Ayan,

Quoted 21 lines · Ayan Kumar Halder

We have written the requirements for some of the commands of the XEN_VERSION hypercall.

---

.../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
.../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
.../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
4 files changed, 182 insertions(+)

create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +0 -0
new file mode 100644
index 0000000000..1dad2b84c2

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 9

Quoted 9 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +9 -0
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".

I would rather not have a requirement that will need changing every time. Could we turn this into a description and link this to where we store the version ?

Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +7 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 26

Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +10 -0
+
+Capabilities AArch32
+--------------------
+
+`XenSwdgn~arm64_capabilities_aarch32~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-armv7l" when it
+detects that the cpu is running in AArch32 mode.
+

Same here and also you have a "when" here and not in previous one.

Quoted 13 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +7 -0
+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..8bb7a66576

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,65 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version
+-------
+
+`XenSwdgn~version~1`
+
+Description:
+Xen shall have a internal constant storing the version number coming from the
+Makefile.

If you go this far i think you should give the name of the constant.

Quoted 6 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 storing the sub version number coming from
+the Makefile.

Same here, please name it.

Quoted 6 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 42

Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10 -0
+ - `XenProd~version_hyp_version_cmd~1`
+
+Extraversion
+------------
+
+`XenSwdgn~extraversion~1`
+
+Description:
+Xen shall have a internal constant string storing the extraversion coming from
+the build environment.

Same here.

Quoted 6 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 58

Quoted 10 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10 -0
+ - `XenProd~version_hyp_extraversion_cmd~1`
+
+Changeset
+---------
+
+`XenSwdgn~changeset~1`
+
+Description:
+Xen shall have a internal constant string storing the date, time and git hash
+of the last change made to Xen's codebase.

Same here.
Also i would use the comment here and in previous reqs to give an example.

Quoted 25 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/index.rst +2 -0
index d8683edce7..b85af19d19 100644
@@ -14,3 +14,5 @@ Requirements documentation
   design-reqs/arm64/generic-timer
   design-reqs/arm64/sbsa-uart
   design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index fdb8da04e1..10bc7b6e87 100644
@@ -59,3 +59,85 @@ Covers:

Needs:
- XenSwdgn

docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 69

Quoted 8 lines
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
+version in the domain's x0 register.

Somehow you will need a req saying that how and hypercall is specified in general and then one req per hypercall:
Xen hypercall number 0 shall return the Xen version in register 0. I would also prevent saying x0 which would make this aarch64 specific.

docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 74

Quoted 5 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +5 -0
+
+Rationale:
+
+Comments:
+Xen version is composed of major and minor number.

Can't we link to the requirement defining where the version is stored ?

Quoted 72 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +69 -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.
+
+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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#3 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

Apologies for the delay in response. I am working on v2 , but need some clarifications.

Quoted 25 lines
Quoted 25 lines · Ayan Kumar Halder

We have written the requirements for some of the commands of the XEN_VERSION hypercall.

---

.../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
.../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
.../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
4 files changed, 182 insertions(+)

create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +3 -0
new file mode 100644
index 0000000000..1dad2b84c2
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
Quoted 8 lines

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 9

Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +6 -0
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".

I would rather not have a requirement that will need changing every time. Could we turn this into a description and link this to where we store the version ?

I tried the follow the discussion between Julien and you. We do not get the version from the Makefile ie 3.0 is hardcoded.

So, does the following look ok

Xen shall have an internal constant string to denote that the cpu is running in arm64 mode.

Quoted 11 lines
Quoted 11 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
+Capabilities AArch32
+--------------------
Quoted 8 lines

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 26

Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +7 -0
+
+`XenSwdgn~arm64_capabilities_aarch32~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-armv7l" when it
+detects that the cpu is running in AArch32 mode.
+

Same here and also you have a "when" here and not in previous one.

Xen shall have a internal constant string to denote that the cpu is running in arm32 mode.

Quoted 17 lines
Quoted 17 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +7 -0
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +3 -0
new file mode 100644
index 0000000000..8bb7a66576
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version
Quoted 8 lines

docs/fusa/reqs/design-reqs/version_hypercall.rst line 10

Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+-------
+
+`XenSwdgn~version~1`
+
+Description:
+Xen shall have a internal constant storing the version number coming from the
+Makefile.

If you go this far i think you should give the name of the constant.

Xen shall have a internal constant (XEN_VERSION) the version number coming from the Makefile.

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

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 storing the sub version number coming from
+the Makefile.

Same here, please name it.

Xen shall have a internal constant (XEN_SUBVERSION) storing the sub version number coming from the Makefile.

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`
+
+Extraversion
Quoted 8 lines

docs/fusa/reqs/design-reqs/version_hypercall.rst line 42

Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+------------
+
+`XenSwdgn~extraversion~1`
+
+Description:
+Xen shall have a internal constant string storing the extraversion coming from
+the build environment.

Same here.

Xen shall have a internal constant (XEN_EXTRAVERSION) storing the extraversion coming from the build environment.

Quoted 11 lines
Quoted 11 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_extraversion_cmd~1`
+
+Changeset
+---------
Quoted 8 lines

docs/fusa/reqs/design-reqs/version_hypercall.rst line 58

Quoted 6 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +6 -0
+
+`XenSwdgn~changeset~1`
+
+Description:
+Xen shall have a internal constant string storing the date, time and git hash
+of the last change made to Xen's codebase.

Same here.
Also i would use the comment here and in previous reqs to give an example.

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.

Quoted 26 lines
Quoted 26 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/index.rst +2 -0
index d8683edce7..b85af19d19 100644
@@ -14,3 +14,5 @@ Requirements documentation
    design-reqs/arm64/generic-timer
    design-reqs/arm64/sbsa-uart
    design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index fdb8da04e1..10bc7b6e87 100644
@@ -59,3 +59,85 @@ Covers:

Needs:
- XenSwdgn

Quoted 10 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 69

Quoted 8 lines
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
+version in the domain's x0 register.

Somehow you will need a req saying that how and hypercall is specified in general and then one req per hypercall:

We have a market requirement, if this looks fine

Xen shall provide an interface for the domains to retrieve Xen's version, type and compilation information.

Quoted 2 lines

Xen hypercall number 0 shall return the Xen version in register 0. I would also prevent saying x0 which would make this aarch64 specific.

Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen's version in the domain's register 0.

Quoted 7 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 74

Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +5 -0
+
+Rationale:
+
+Comments:
+Xen version is composed of major and minor number.

Can't we link to the requirement defining where the version is stored ?

Yes, this is linked to the design requirement

XenSwdgn~version~1 and XenSwdgn~subversion~1
- Ayan

Quoted 77 lines
Quoted 73 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +69 -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.
+
+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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#4 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

Hi Ayan,

Quoted 44 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

Apologies for the delay in response. I am working on v2 , but need some clarifications.

Quoted 25 lines
Quoted 25 lines · Ayan Kumar Halder

We have written the requirements for some of the commands of the XEN_VERSION hypercall.

---

.../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
.../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
.../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
4 files changed, 182 insertions(+)

create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +3 -0
new file mode 100644
index 0000000000..1dad2b84c2
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
Quoted 8 lines

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 9

Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +6 -0
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".

I would rather not have a requirement that will need changing every time. Could we turn this into a description and link this to where we store the version ?

Quoted 6 lines

I tried the follow the discussion between Julien and you. We do not get the version from the Makefile ie 3.0 is hardcoded.

So, does the following look ok

Xen shall have an internal constant string to denote that the cpu is running in arm64 mode.

ok for me.

Quoted 19 lines
Quoted 11 lines
Quoted 11 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
+Capabilities AArch32
+--------------------
Quoted 8 lines

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 26

Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +7 -0
+
+`XenSwdgn~arm64_capabilities_aarch32~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-armv7l" when it
+detects that the cpu is running in AArch32 mode.
+

Same here and also you have a "when" here and not in previous one.

Quoted 2 lines

Xen shall have a internal constant string to denote that the cpu is running in arm32 mode.

ok

Quoted 25 lines
Quoted 17 lines
Quoted 17 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +7 -0
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +3 -0
new file mode 100644
index 0000000000..8bb7a66576
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version
Quoted 8 lines

docs/fusa/reqs/design-reqs/version_hypercall.rst line 10

Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+-------
+
+`XenSwdgn~version~1`
+
+Description:
+Xen shall have a internal constant storing the version number coming from the
+Makefile.

If you go this far i think you should give the name of the constant.

Quoted 2 lines

Xen shall have a internal constant (XEN_VERSION) the version number coming from the Makefile.

you are missing a "storing"

Quoted 18 lines
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

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 storing the sub version number coming from
+the Makefile.

Same here, please name it.

Quoted 2 lines

Xen shall have a internal constant (XEN_SUBVERSION) storing the sub version number coming from the Makefile.

ok

Quoted 18 lines
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`
+
+Extraversion
Quoted 8 lines

docs/fusa/reqs/design-reqs/version_hypercall.rst line 42

Quoted 7 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+------------
+
+`XenSwdgn~extraversion~1`
+
+Description:
+Xen shall have a internal constant string storing the extraversion coming from
+the build environment.

Same here.

Quoted 2 lines

Xen shall have a internal constant (XEN_EXTRAVERSION) storing the extraversion coming from the build environment.

ok

Quoted 19 lines
Quoted 11 lines
Quoted 11 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_extraversion_cmd~1`
+
+Changeset
+---------
Quoted 8 lines

docs/fusa/reqs/design-reqs/version_hypercall.rst line 58

Quoted 6 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +6 -0
+
+`XenSwdgn~changeset~1`
+
+Description:
+Xen shall have a internal constant string storing the date, time and git hash
+of the last change made to Xen's codebase.

Same here.
Also i would use the comment here and in previous reqs to give an example.

Quoted 2 lines

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.

ok

Quoted 37 lines
Quoted 26 lines
Quoted 26 lines
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +7 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/index.rst +2 -0
index d8683edce7..b85af19d19 100644
@@ -14,3 +14,5 @@ Requirements documentation
   design-reqs/arm64/generic-timer
   design-reqs/arm64/sbsa-uart
   design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index fdb8da04e1..10bc7b6e87 100644
@@ -59,3 +59,85 @@ Covers:

Needs:
- XenSwdgn

Quoted 10 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 69

Quoted 8 lines
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
+version in the domain's x0 register.

Somehow you will need a req saying that how and hypercall is specified in general and then one req per hypercall:

Quoted 4 lines

We have a market requirement, if this looks fine

Xen shall provide an interface for the domains to retrieve Xen's version, type and compilation information.

ok

Quoted 5 lines
Quoted 3 lines

Xen hypercall number 0 shall return the Xen version in register 0. I would also prevent saying x0 which would make this aarch64 specific.

Xen shall provide a command (num 0) for hypercall (num 17) to retrieve Xen's version in the domain's register 0.

ok

Quoted 11 lines
Quoted 7 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst Covers: · line 74

Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +5 -0
+
+Rationale:
+
+Comments:
+Xen version is composed of major and minor number.

Can't we link to the requirement defining where the version is stored ?

Yes, this is linked to the design requirement

XenSwdgn~version~1 and XenSwdgn~subversion~1

Good

Bertrand

Quoted 77 lines

- Ayan

Quoted 75 lines
Quoted 73 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +69 -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.
+
+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:
+ - XenSwdgn
Signature · 1 line
2.25.1

Cheers
Bertrand

#5 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

In reply to Ayan Kumar Halder

Hi,

Quoted 21 lines · Ayan Kumar Halder

We have written the requirements for some of the commands of the XEN_VERSION
hypercall.

---
 .../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
 .../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 .../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
 4 files changed, 182 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +0 -0
new file mode 100644
index 0000000000..1dad2b84c2

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst line 9

Quoted 9 lines
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +9 -0
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".

Can you explain why we need to specify how Xen is storing the string? At least to me this feels a bit overkill. What matters is what/how the VM is seen.

Quoted 157 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 storing "xen-3.0-armv7l" when it
+detects that the cpu is running in AArch32 mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +9 -0
new file mode 100644
index 0000000000..8bb7a66576
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version
+-------
+
+`XenSwdgn~version~1`
+
+Description:
+Xen shall have a internal constant storing the version number coming from

the

docs/fusa/reqs/design-reqs/version_hypercall.rst new file +16 -0
+Makefile.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_version_cmd~1`
+
+Subversion
+----------
+
+`XenSwdgn~subversion~1`
+
+Description:
+Xen shall have a internal constant storing the sub version number coming

from

docs/fusa/reqs/design-reqs/version_hypercall.rst new file +16 -0
+the Makefile.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_version_cmd~1`
+
+Extraversion
+------------
+
+`XenSwdgn~extraversion~1`
+
+Description:
+Xen shall have a internal constant string storing the extraversion coming

from

docs/fusa/reqs/design-reqs/version_hypercall.rst new file +16 -0
+the build environment.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_extraversion_cmd~1`
+
+Changeset
+---------
+
+`XenSwdgn~changeset~1`
+
+Description:
+Xen shall have a internal constant string storing the date, time and git

hash

docs/fusa/reqs/design-reqs/version_hypercall.rst new file +8 -0
+of the last change made to Xen's codebase.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/index.rst +2 -0
index d8683edce7..b85af19d19 100644
@@ -14,3 +14,5 @@ Requirements documentation
    design-reqs/arm64/generic-timer
    design-reqs/arm64/sbsa-uart
    design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/version_hypercall.rst +7 -0
index fdb8da04e1..10bc7b6e87 100644
@@ -59,3 +59,85 @@ Covers:
 Needs:
  - XenSwdgn
 
+Version command
+---------------
+
+`XenProd~version_hyp_version_cmd~1`
+
+Description:
+Xen shall provide a command (num 0) for  hypercall (num 17) to retrieve

Xen's

docs/fusa/reqs/product-reqs/version_hypercall.rst +26 -0
+version in the domain's x0 register.
 
 
+
+Rationale:
+
+Comments:
+Xen version is composed of major and minor number.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Extraversion command
+--------------------
+
+`XenProd~version_hyp_extraversion_cmd~1`
+
+Description:
+Xen shall provide a command (num 1) for hypercall (num 17) to copy its
+extraversion in the domain's buffer.
 
 
+
+Rationale:
+
+Comments:
+Xen's extra version consists of a string passed with 'XEN_VENDORVERSION'
Quoted 2 lines

command
+line parameter while building Xen.

Not really. It returns a truncated version if it is too large. You likely want to describe command 11.

Quoted 55 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst +35 -0
+
+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

docs/fusa/reqs/product-reqs/version_hypercall.rst +6 -0
+to the domain's buffer.
+
+Rationale:
+
+Comments:
+Changeset is string denoting the date, time and git hash of the last

change

docs/fusa/reqs/product-reqs/version_hypercall.rst +7 -1
+made to Xen's codebase.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
--

2.25.1

#6 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

Hi Julien,

Welcome back :-)

Quoted 34 lines · Julien Grall

Hi,

On Tue, 14 Jan 2025 at 16:50, Ayan Kumar Halder <[email protected]> wrote:
We have written the requirements for some of the commands of the XEN_VERSION hypercall.

---
 .../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
 .../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 .../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
 4 files changed, 182 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +9 -0
new file mode 100644
index 0000000000..1dad2b84c2
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".
Quoted 1 line

Can you explain why we need to specify how Xen is storing the string? At least to me this feels a bit overkill. What matters is what/how the VM is seen.

This is a design requirement and as such it should be testable so it would be easier to have something saying:
Xen shall have a constant named XXX storing YYY.

Just saying "an internal constant" seem a bit limited here and not saying much that could be tested easily.

Why do you think this would be an overkill ? do you expect the constant name to change a lot ? I would see more as an overkill the fact that the value is stored in a requirement.

Cheers
Bertrand

#7 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

Quoted 3 lines · Bertrand Marquis

Hi Julien,

Welcome back :-)

I am not fully back yet but I have a bit of spare time to go through xen-devel :).

Quoted 40 lines
Quoted 2 lines

On 29 Jan 2025, at 16:33, Julien Grall <[email protected]>

Quoted 4 lines · wrote:

Hi,

On Tue, 14 Jan 2025 at 16:50, Ayan Kumar Halder <

Quoted 1 line · [email protected]> wrote:

We have written the requirements for some of the commands of the

XEN_VERSION

Quoted 10 lines

hypercall.

---
 .../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
 .../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 .../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
 4 files changed, 182 insertions(+)
 create mode 100644

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst

Review

Quoted 3 lines
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
(quoted diff) +0 -0

b/docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst

Quoted 15 lines

new file mode 100644
index 0000000000..1dad2b84c2

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +9 -0
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".
Quoted 7 lines
Quoted 1 line

Can you explain why we need to specify how Xen is storing the string? At

least to me this feels a bit overkill. What matters is what/how the VM is seen.

This is a design requirement and as such it should be testable so it would be easier to have something saying:
Xen shall have a constant named XXX storing YYY.

Reading this, would it be better to tie to the variable in the makefile? This would be closer to how a user would set it and how one would test it.

Quoted 6 lines

Just saying "an internal constant" seem a bit limited here and not saying much that could be tested easily.

Why do you think this would be an overkill ? do you expect the constant name to change a lot ?

I don’t expect the constant name to change. It is more that this is an internal implementation quite far to how the user would set it (see above).

Cheers,

Quoted 7 lines

I would see more as an overkill the fact that the value is stored in a requirement.

Cheers
Bertrand

#8 lore raw

Re: [PATCH v1 2/2] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

Hi Julien,

Quoted 9 lines · Julien Grall

On Wed, 29 Jan 2025 at 12:49, Bertrand Marquis <[email protected]> wrote:
Hi Julien,

Welcome back :-)

I am not fully back yet but I have a bit of spare time to go through xen-devel :).

Then enjoy your remaining free time to, nothing urgent on the ML ;-)

Quoted 37 lines
Quoted 37 lines · Julien Grall

Hi,

On Tue, 14 Jan 2025 at 16:50, Ayan Kumar Halder <[email protected]> wrote:
We have written the requirements for some of the commands of the XEN_VERSION hypercall.

---
 .../design-reqs/arm64/version_hypercall.rst   | 33 ++++++++
 .../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 .../reqs/product-reqs/version_hypercall.rst   | 82 +++++++++++++++++++
 4 files changed, 182 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +9 -0
new file mode 100644
index 0000000000..1dad2b84c2
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall have a internal constant string storing "xen-3.0-aarch64".
Quoted 6 lines
Quoted 1 line

Can you explain why we need to specify how Xen is storing the string? At least to me this feels a bit overkill. What matters is what/how the VM is seen.

This is a design requirement and as such it should be testable so it would be easier to have something saying:
Xen shall have a constant named XXX storing YYY.

Reading this, would it be better to tie to the variable in the makefile? This would be closer to how a user would set it and how one would test it.

Definitely yes. The more direct the variable, the better it is.
As the Makefile variable is what we modify, I agree that this should point to it.

Quoted 9 lines

Just saying "an internal constant" seem a bit limited here and not saying much that could be tested easily.

Why do you think this would be an overkill ? do you expect the constant name to change a lot ?

I don’t expect the constant name to change. It is more that this is an internal implementation quite far to how the user would set it (see above).

Agree and the Makefile variable seems the best way.
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.

Cheers
Bertrand

Quoted 8 lines

Cheers,

I would see more as an overkill the fact that the value is stored in a requirement.

Cheers
Bertrand

#9 lore raw
In reply to Ayan Kumar Halder
Quoted 6 lines · Ayan Kumar Halder
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +0 -0
new file mode 100644
index 0000000000..fdb8da04e1

docs/fusa/reqs/product-reqs/version_hypercall.rst line 8

Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +8 -0
@@ -0,0 +1,61 @@
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+Xen shall return 0 in case of success or one of the error codes as defined in
+https://man7.org/linux/man-pages/man3/errno.3.html.

Xen's errors live in public/errno.h

They share a lot in common with Linux (for historical reasons), but they are critically not Linux errnos because Xen supports OSes which aren't Linux.  xenstored for example sends errors as text rather than numbers.

Also, that's not the return value ABI of __HYPERVISOR_xen_version.  Some subops return a positive value instead of 0 on success.

And if you're wondering "hey, isn't that ambiguous in extreme cases", yes it is.  Xen's hypercall API/ABI are a disaster.

~Andrew

#10 lore raw

Hi Andrew,

Quoted 16 lines · Andrew Cooper
Quoted 6 lines · Ayan Kumar Halder
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +0 -0
new file mode 100644
index 0000000000..fdb8da04e1

docs/fusa/reqs/product-reqs/version_hypercall.rst line 8

Quoted 8 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +8 -0
@@ -0,0 +1,61 @@
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+Xen shall return 0 in case of success or one of the error codes as defined in
+https://man7.org/linux/man-pages/man3/errno.3.html.

Xen's errors live in public/errno.h

Ack.

Quoted 7 lines

They share a lot in common with Linux (for historical reasons), but they are critically not Linux errnos because Xen supports OSes which aren't Linux.  xenstored for example sends errors as text rather than numbers.

Also, that's not the return value ABI of __HYPERVISOR_xen_version.  Some subops return a positive value instead of 0 on success.

Yes, my bad. 'XENVER_version' cmd will return the actual version number on success. I should reword this as

"Xen shall use the error codes defined in xen/include/public/errno.h , as a return value in case of failure."

And a separate requirement will be

"Xen shall return a non negative value in case of success."

Let me know if this sounds ok.

Quoted 3 lines

And if you're wondering "hey, isn't that ambiguous in extreme cases", yes it is.  Xen's hypercall API/ABI are a disaster.

Ack. :)

- Ayan

Quoted 2 lines

~Andrew

#11 lore raw
In reply to Ayan Kumar Halder

Hi Ayan,

Quoted 23 lines · Ayan Kumar Halder

In the current patch, we have defined the requirements which are common for all the commands.

---

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 52 ++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 131 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..66dbcc3026
@@ -0,0 +1,52 @@
+.. 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:
+Domains shall use the Arm instruction 'hvc' to interact with Xen.

Why are those requirements defining what "Domains" should do ? Shouldn't we define them as what Xen shall do ?
Something around:
Xen shall treat Domain hypercall exceptions and hypercall requests from Domains.

Or something around this idea.

Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +7 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`

docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 29

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:
+Domains shall use register x0 to pass first parameter, x1 to pass second
+parameter and so on.

Same

Quoted 68 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +23 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +16 -0
+
+Version hypercall
+-----------------
+
+`XenMkt~version_hypercall~1`
+
+Description:
+Xen shall provide an interface for the domains to retrieve Xen's version, type
+and compilation information.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +3 -0
new file mode 100644
index 0000000000..fdb8da04e1
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall

docs/fusa/reqs/product-reqs/version_hypercall.rst line 13

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+=================
+
+First Parameter
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Domain shall pass the first argument (as an integer) to denote the command
+number for the hypercall.

Same here should be turned as Xen shall.

Quoted 9 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +9 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:

docs/fusa/reqs/product-reqs/version_hypercall.rst line 32

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+ - XenSwdgn
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Domain shall pass the second argument as a pointer to buffer in guest memory.
+

Ditto

Quoted 32 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29 -0
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+Xen shall return 0 in case of success or one of the error codes as defined in
+https://man7.org/linux/man-pages/man3/errno.3.html.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
Signature · 1 line
2.25.1

Cheers
Bertrand

#12 lore raw
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I need some clarifications.

Quoted 39 lines
Quoted 24 lines · Ayan Kumar Halder

In the current patch, we have defined the requirements which are common for all the commands.

---

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 52 ++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 131 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..66dbcc3026
@@ -0,0 +1,52 @@
+.. 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:
+Domains shall use the Arm instruction 'hvc' to interact with Xen.

Why are those requirements defining what "Domains" should do ? Shouldn't we define them as what Xen shall do ?
Something around:
Xen shall treat Domain hypercall exceptions and hypercall requests from Domains.

Quoted 1 line

Or something around this idea.

Xen shall treat domain hypercall exception as hypercall requests.

Quoted 5 lines

docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 16

Quoted 5 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +4 -0
+
+Rationale:
+
+Comments:

Hypercall is one of the communication mechanism between Xen and domains. Domains use hypercalls for various requests to Xen.
Domains use 'hvc' instruction to invoke hypercalls.

Quoted 6 lines
Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +6 -0
+
+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 29

Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +7 -0
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Domains shall use register x0 to pass first parameter, x1 to pass second
+parameter and so on.

Same

Xen shall use the register 0 to read the first parameter, register 1 for second parameter and so on, for domain hypercall requests.

Quoted 72 lines
Quoted 72 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +23 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +16 -0
+
+Version hypercall
+-----------------
+
+`XenMkt~version_hypercall~1`
+
+Description:
+Xen shall provide an interface for the domains to retrieve Xen's version, type
+and compilation information.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
new file mode 100644
index 0000000000..fdb8da04e1
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
Quoted 8 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst line 13

Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7 -0
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Domain shall pass the first argument (as an integer) to denote the command
+number for the hypercall.

Same here should be turned as Xen shall.

Xen shall treat the first argument (as an integer) to denote the command number for the hypercall.

Quoted 13 lines
Quoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +12 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Second Parameter
Quoted 8 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst line 32

Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7 -0
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Domain shall pass the second argument as a pointer to buffer in guest memory.
+

Ditto

Xen shall treat the second argument as a pointer to buffer in guest memory.
- Ayan

Quoted 37 lines
Quoted 33 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29 -0
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+Xen shall return 0 in case of success or one of the error codes as defined in
+https://man7.org/linux/man-pages/man3/errno.3.html.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
Signature · 1 line
2.25.1

Cheers
Bertrand

#13 lore raw

Hi Ayan,

Quoted 49 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I need some clarifications.

Quoted 39 lines
Quoted 24 lines · Ayan Kumar Halder

In the current patch, we have defined the requirements which are common for all the commands.

---

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 52 ++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 131 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..66dbcc3026
@@ -0,0 +1,52 @@
+.. 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:
+Domains shall use the Arm instruction 'hvc' to interact with Xen.

Why are those requirements defining what "Domains" should do ? Shouldn't we define them as what Xen shall do ?
Something around:
Xen shall treat Domain hypercall exceptions and hypercall requests from Domains.

Quoted 2 lines
Quoted 1 line

Or something around this idea.

Xen shall treat domain hypercall exception as hypercall requests.

sounds good

Quoted 8 lines
Quoted 5 lines

docs/fusa/reqs/design-reqs/arm64/hypercall.rst line 16

Quoted 5 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +4 -0
+
+Rationale:
+
+Comments:

Hypercall is one of the communication mechanism between Xen and domains. Domains use hypercalls for various requests to Xen.
Domains use 'hvc' instruction to invoke hypercalls.

ok

Quoted 14 lines
Quoted 6 lines
Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +6 -0
+
+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 29

Quoted 7 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +7 -0
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Domains shall use register x0 to pass first parameter, x1 to pass second
+parameter and so on.

Same

Quoted 2 lines

Xen shall use the register 0 to read the first parameter, register 1 for second parameter and so on, for domain hypercall requests.

ok

Quoted 80 lines
Quoted 72 lines
Quoted 72 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +23 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +16 -0
+
+Version hypercall
+-----------------
+
+`XenMkt~version_hypercall~1`
+
+Description:
+Xen shall provide an interface for the domains to retrieve Xen's version, type
+and compilation information.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
new file mode 100644
index 0000000000..fdb8da04e1
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
Quoted 8 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst line 13

Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7 -0
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Domain shall pass the first argument (as an integer) to denote the command
+number for the hypercall.

Same here should be turned as Xen shall.

Quoted 2 lines

Xen shall treat the first argument (as an integer) to denote the command number for the hypercall.

ok

Quoted 21 lines
Quoted 13 lines
Quoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +12 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Second Parameter
Quoted 8 lines

docs/fusa/reqs/product-reqs/version_hypercall.rst line 32

Quoted 7 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +7 -0
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Domain shall pass the second argument as a pointer to buffer in guest memory.
+

Ditto

Quoted 1 line

Xen shall treat the second argument as a pointer to buffer in guest memory.

You might want to specify the addressing type (PA/IPA/VA) here.

Bertrand

Quoted 36 lines

- Ayan

Quoted 35 lines
Quoted 33 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29 -0
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+Xen shall return 0 in case of success or one of the error codes as defined in
+https://man7.org/linux/man-pages/man3/errno.3.html.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
Signature · 1 line
2.25.1

Cheers
Bertrand