Skip to contentSkip to conversation

docs: fusa: Define the requirements for XEN_VERSION hypercall.

PATCH Superseded Ayan Kumar Halder 4 participants 11 messages Feb 27, 2025 – Feb 28, 2025

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

 .../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
 .../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
 4 files changed, 134 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/hypercall.rst
 create mode 100644 docs/fusa/reqs/product-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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

62 lines not on this page · raw message

Signature · 1 line
2.25.1
#1 lore raw

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

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

---
Changes from -

v1 - 1. Reworded the requirement so as to avoid mentioining variable names or hardcoded strings. Otherwise, one would need to change the requirement each time the code changes.

 .../fusa/reqs/design-reqs/arm64/hypercall.rst |  6 +-
 .../design-reqs/arm64/version_hypercall.rst   | 34 ++++++++
 .../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 .../reqs/product-reqs/version_hypercall.rst   | 83 +++++++++++++++++++
 5 files changed, 187 insertions(+), 3 deletions(-)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +3 -3
index ffd883260c..b6f99af023 100644
@@ -28,8 +28,8 @@ Parameters
 `XenSwdgn~arm64_hyp_param~1`
 
 Description:
-Xen shall use x0 to read the first parameter, x1 for second parameter and so
-on, for domain hypercall requests.
+Xen shall use the first register to read the first parameter, second register
+for second parameter and so on, for domain hypercall requests.
 
 Rationale:
 
@@ -45,7 +45,7 @@ Return value
 `XenSwdgn~arm64_ret_val~1`
 
 Description:
-Xen shall store the return value in x0 register.
+Xen shall store the return value in first register.
 
 Rationale:
 
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +34 -0
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 +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 +83 -0

89 lines not on this page · raw message

Signature · 1 line
2.25.1
Reviewed-by on v2 2/2
#2 lore raw

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

Hi Ayan,

Quoted 41 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Reworded the requirement so as to avoid mentioining variable names or hardcoded strings. Otherwise, one would need to change the requirement each time the code changes.

.../fusa/reqs/design-reqs/arm64/hypercall.rst |  6 +-
.../design-reqs/arm64/version_hypercall.rst   | 34 ++++++++
.../reqs/design-reqs/version_hypercall.rst    | 65 +++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
.../reqs/product-reqs/version_hypercall.rst   | 83 +++++++++++++++++++
5 files changed, 187 insertions(+), 3 deletions(-)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst +0 -0
index ffd883260c..b6f99af023 100644
@@ -28,8 +28,8 @@ Parameters

XenSwdgn~arm64_hyp_param~1

Description:

docs/fusa/reqs/design-reqs/arm64/hypercall.rst +2 -2
-Xen shall use x0 to read the first parameter, x1 for second parameter and so
-on, for domain hypercall requests.
+Xen shall use the first register to read the first parameter, second register
+for second parameter and so on, for domain hypercall requests.

Rationale:

docs/fusa/reqs/design-reqs/arm64/hypercall.rst +0 -0
@@ -45,7 +45,7 @@ Return value

XenSwdgn~arm64_ret_val~1

Description:

docs/fusa/reqs/design-reqs/arm64/hypercall.rst Return value · line 48

Quoted 2 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +1 -1
-Xen shall store the return value in x0 register.
+Xen shall store the return value in first register.

It seems that those changes should be in the previous patch directly.

With that fixed:

Cheers
Bertrand

Quoted 221 lines

Rationale:

docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +34 -0
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 +65 -0
new file mode 100644
index 0000000000..edc5672e83
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version
+-------
+
+`XenSwdgn~version~1`
+
+Description:
+Xen shall have a internal constant (XEN_VERSION) storing the version number
+coming from the Makefile.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_version_cmd~1`
+
+Subversion
+----------
+
+`XenSwdgn~subversion~1`
+
+Description:
+Xen shall have a internal constant (XEN_SUBVERSION) storing the sub version
+number coming from the Makefile.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_version_cmd~1`
+
+Extraversion
+------------
+
+`XenSwdgn~extraversion~1`
+
+Description:
+Xen shall have a internal constant (XEN_EXTRAVERSION) storing the extraversion
+coming from the build environment.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_extraversion_cmd~1`
+
+Changeset
+---------
+
+`XenSwdgn~changeset~1`
+
+Description:
+Xen shall have a internal constant string (XEN_CHANGESET) storing the date,
+time and git hash of the last change made to Xen's codebase.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/index.rst +2 -0
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 03221f70c3..ae72b22556 100644
@@ -54,6 +54,89 @@ Rationale:
 

Comments:

docs/fusa/reqs/product-reqs/version_hypercall.rst +83 -0
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Version command
+---------------
+
+`XenProd~version_hyp_version_cmd~1`
+
+Description:
+Xen shall provide a command (num 0) for  hypercall (num 17) to retrieve Xen's
+version in the domain's register 0.
+
+Rationale:
+
+Comments:
+Xen version is composed of major and minor number.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Extraversion command
+--------------------
+
+`XenProd~version_hyp_extraversion_cmd~1`
+
+Description:
+Xen shall provide a command (num 1) for hypercall (num 17) to copy its
+extraversion in the domain's buffer.
+
+Rationale:
+
+Comments:
+Xen's extra version consists of a string passed with 'XEN_VENDORVERSION' command
+line parameter while building Xen.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Capabilities command
+--------------------
+
+`XenProd~version_hyp_capabilities_cmd~1`
+
+Description:
+Xen shall provide a command (num 3) for hypercall (num 17) to copy its
+capabilities to the domain's buffer.
+
+Rationale:
+
+Comments:
+Capabilities related information is represented by char[1024].
+For Arm64, the capabilities should contain "xen-3.0-aarch64" string.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Changeset command
+-----------------
+
+`XenProd~version_hyp_changeset_cmd~1`
+
+Description:
+Xen shall provide a command (num 4) for hypercall (num 17) to copy changeset
+to the domain's buffer.
+
+Rationale:
+
+Comments:
+Changeset is string denoting the date, time and git hash of the last change
+made to Xen's codebase.
+

Covers:
- XenMkt~version_hypercall~1

Signature · 1 line
2.25.1
#3 lore raw
In reply to Ayan Kumar Halder

Hi Ayan,

Quoted 128 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall

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

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

You speak of argument here and parameter earlier.
I would rephrase to: the first argument of an hypercall exception as the command number for the hypercall.

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.
+

Same here on argument vs parameter.

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

This is a very imprecise req as it does not states what can fail and what should be returned exactly. Do we want to be that generic ? if yes then this might be a requirement valid for any hypercall.

Cheers
Bertrand

Quoted 14 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
Signature · 1 line
2.25.1
#4 lore raw
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I have just some clarifications.

Quoted 133 lines
Quoted 133 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +7 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
Quoted 8 lines

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

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

You speak of argument here and parameter earlier.
I would rephrase to: the first argument of an hypercall exception as the command number for the hypercall.

Ack

Should I do this everywhere ?

s/parameter/argument

That would make it consistent.

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.
+

Same here on argument vs parameter.

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

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

Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

This is a very imprecise req as it does not states what can fail and what should be returned exactly. Do we want to be that generic ? if yes then this might be a requirement valid for any hypercall.

Yes, you are correct.

I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.

IOW, we don't need to validate each and every error code returned by the hypercall.

Or should we just drop this requirement ?

- Ayan

Quoted 18 lines

Cheers
Bertrand

Quoted 14 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
Signature · 1 line
2.25.1
#5 lore raw

Hi Ayan,

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

Hi Ayan,

Hi Bertrand,

I have just some clarifications.

Quoted 133 lines
Quoted 133 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +7 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
Quoted 8 lines

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

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

You speak of argument here and parameter earlier.
I would rephrase to: the first argument of an hypercall exception as the command number for the hypercall.

Quoted 7 lines

Ack

Should I do this everywhere ?

s/parameter/argument

That would make it consistent.

Yes definitely

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.
+

Same here on argument vs parameter.

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

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

Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

This is a very imprecise req as it does not states what can fail and what should be returned exactly. Do we want to be that generic ? if yes then this might be a requirement valid for any hypercall.

Quoted 7 lines

Yes, you are correct.

I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.

IOW, we don't need to validate each and every error code returned by the hypercall.

Or should we just drop this requirement ?

I think you should move this requirement and make it a generic one valid for all hypercalls.

Now at some point you might have to describe which error is caused by what problem as part of your hypercall interface definition.
ie: one generic product req and per hypercall design req describing the error cases.

At the end you should have a test to trigger each error condition and that test will be linked to the design req corresponding.

Cheers
Bertrand

Quoted 20 lines

- Ayan

Quoted 17 lines

Cheers
Bertrand

Quoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
Signature · 1 line
2.25.1
#6 lore raw
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

Quoted 201 lines
Quoted 150 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I have just some clarifications.

Quoted 132 lines
Quoted 132 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +7 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
Quoted 8 lines

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

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

You speak of argument here and parameter earlier.
I would rephrase to: the first argument of an hypercall exception as the command number for the hypercall.

Quoted 7 lines

Ack

Should I do this everywhere ?

s/parameter/argument

That would make it consistent.

Yes definitely

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.
+

Same here on argument vs parameter.

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

This is a very imprecise req as it does not states what can fail and what should be returned exactly. Do we want to be that generic ? if yes then this might be a requirement valid for any hypercall.

Quoted 8 lines
Quoted 7 lines

Yes, you are correct.

I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.

IOW, we don't need to validate each and every error code returned by the hypercall.

Or should we just drop this requirement ?

I think you should move this requirement and make it a generic one valid for all hypercalls.

Yes, I will place it under hypercall.rst.

Quoted 3 lines

Now at some point you might have to describe which error is caused by what problem as part of your hypercall interface definition.
ie: one generic product req and per hypercall design req describing the error cases.

Agreed.

And an example design requirement which will be linked is :-

Xen shall return -EFAULT if it encounters an error while copying the extraversion string to domain's buffer.

Is this what you have in mind ?

Quoted 2 lines

At the end you should have a test to trigger each error condition and that test will be linked to the design req corresponding.

Ack.

- Ayan

Quoted 23 lines

Cheers
Bertrand

Quoted 18 lines

- Ayan

Quoted 16 lines

Cheers
Bertrand

Quoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
Signature · 1 line
2.25.1
#7 lore raw

Hi Ayan,

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

Hi Ayan,

Hi Bertrand,

Quoted 201 lines
Quoted 150 lines · Ayan Kumar Halder
Quoted 1 line · Bertrand Marquis

Hi Ayan,

Hi Bertrand,

I have just some clarifications.

Quoted 132 lines
Quoted 132 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
docs/fusa/reqs/index.rst                      |  2 +
docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
.../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +55 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +7 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
Quoted 8 lines

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

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

You speak of argument here and parameter earlier.
I would rephrase to: the first argument of an hypercall exception as the command number for the hypercall.

Quoted 7 lines

Ack

Should I do this everywhere ?

s/parameter/argument

That would make it consistent.

Yes definitely

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.
+

Same here on argument vs parameter.

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

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

This is a very imprecise req as it does not states what can fail and what should be returned exactly. Do we want to be that generic ? if yes then this might be a requirement valid for any hypercall.

Quoted 8 lines
Quoted 7 lines

Yes, you are correct.

I am thinking of pushing this further up ie have this requirement at market level and leave it **unlinked** to any product requirement.

IOW, we don't need to validate each and every error code returned by the hypercall.

Or should we just drop this requirement ?

I think you should move this requirement and make it a generic one valid for all hypercalls.

Yes, I will place it under hypercall.rst.

Quoted 3 lines

Now at some point you might have to describe which error is caused by what problem as part of your hypercall interface definition.
ie: one generic product req and per hypercall design req describing the error cases.

Quoted 7 lines

Agreed.

And an example design requirement which will be linked is :-

Xen shall return -EFAULT if it encounters an error while copying the extraversion string to domain's buffer.

Is this what you have in mind ?

Yes it is.
But is it the only error that can be return by the hypercall ?

Bertrand

Quoted 30 lines
Quoted 3 lines

At the end you should have a test to trigger each error condition and that test will be linked to the design req corresponding.

Ack.

- Ayan

Quoted 22 lines

Cheers
Bertrand

Quoted 18 lines

- Ayan

Quoted 16 lines

Cheers
Bertrand

Quoted 13 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
Signature · 1 line
2.25.1
#8 lore raw
In reply to Ayan Kumar Halder

Hi,

Quoted 35 lines · Ayan Kumar Halder

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

  .../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
  docs/fusa/reqs/index.rst                      |  2 +
  docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
  .../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
  4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +9 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`

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

Quoted 10 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +10 -0
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.

Are you trying to describe any hypercalls (e.g. SMCCC, Xen...) or just the Xen one? If the latter, only "hvc #0xEA1" will be used for Xen hypercalls. Other immediate/space will be used for something different (i.e. #0 is used for SMCCC).

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

Quoted 12 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +12 -0
+> +Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.

This implies we are supporting a large number of parameters. However, Xen is only support 5 arguments. So I would just list all the registers.

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

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

You don't seem to describe how the hypercall number is passed. Is this intended?

Quoted 78 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14 -0
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +22 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Xen shall treat the first argument (as an integer) to denote the command number
+for the hypercall.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:

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

Quoted 10 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+ - XenSwdgn
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.

We don't support any VA. The VA will need to be mapped with specifc attributes (see include/public/arch-arm.h). Should this be mentioned in the requirement?

Quoted 30 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
Signature · 1 line
Julien Grall
#9 lore raw
Quoted 1 line · Julien Grall

Hi,

Hi Julien/Bertrand,

Quoted 42 lines · Ayan Kumar Halder
Quoted 40 lines

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

  .../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++ docs/fusa/reqs/index.rst                      |  2 + docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++ .../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++

  4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
+Rationale:
Quoted 8 lines

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

Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +3 -0
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and 

domains.

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +2 -0
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.

Are you trying to describe any hypercalls (e.g. SMCCC, Xen...) or just the Xen one? If the latter, only "hvc #0xEA1" will be used for Xen hypercalls. Other immediate/space will be used for something different (i.e. #0 is used for SMCCC).

Yes, only the Xen one. I will mention "hvc #0xEA1".

Quoted 16 lines
Quoted 12 lines

+> +Covers:
+ - XenProd~version_hyp_first_param~1
+ - XenProd~version_hyp_second_param~1

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +8 -0
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second 
Quoted 2 lines

parameter and so
+on, for domain hypercall requests.

This implies we are supporting a large number of parameters. However, Xen is only support 5 arguments. So I would just list all the registers.

Xen shall use the first five cpu core registers to obtain the arguments for domain hypercall requests. Xen shall read the first register for the first argument, second register for the second argument and so on.

@Bertrand :- Does this look ok to you ? I deliberately changed from x0 to first register so that this can be valid for both arm64 and arm32. Please comment.

Quoted 12 lines

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

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

You don't seem to describe how the hypercall number is passed. Is this intended?

Good catch. I will add a requirement.

Xen shall read x16 to obtain the hypercall number.

Xen shall read r12 to obtain the hypercall number.

Quoted 85 lines
Quoted 85 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14 -0
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +0 -0
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 +8 -0
+
+Version hypercall
+-----------------
+
+`XenMkt~version_hypercall~1`
+
+Description:
+Xen shall provide an interface for the domains to retrieve Xen's 

version, type

docs/fusa/reqs/market-reqs/reqs.rst +8 -0
+and compilation information.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +12 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Xen shall treat the first argument (as an integer) to denote the 

command number

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

+XenProd~version_hyp_second_param~1

docs/fusa/reqs/product-reqs/version_hypercall.rst new file +3 -0
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer 

in domain's
+memory.

We don't support any VA. The VA will need to be mapped with specifc attributes (see include/public/arch-arm.h). Should this be mentioned in the requirement?

....as a virtual address (mapped as Normal Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's ....

- Ayan

Quoted 34 lines
Quoted 33 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +18 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes 

defined
+in
http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.

docs/fusa/reqs/product-reqs/version_hypercall.rst new file +10 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file
#10 lore raw

Hi Ayan,

Quoted 72 lines · Ayan Kumar Halder
Quoted 1 line · Julien Grall

Hi,

Hi Julien/Bertrand,

Quoted 41 lines · Ayan Kumar Halder
Quoted 39 lines

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

---
Changes from -

v1 - 1. Fixed XenProd~version_hyp_ret_val~1 requirement as Xen does not return 0 for success in all the cases.
2. Reworded the requirements so as to write them from Xen's perspective (not domain's perspective).

  .../fusa/reqs/design-reqs/arm64/hypercall.rst | 55 +++++++++++++++++
  docs/fusa/reqs/index.rst                      |  2 +
  docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
  .../reqs/product-reqs/version_hypercall.rst   | 61 +++++++++++++++++++
  4 files changed, 134 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +13 -0
new file mode 100644
index 0000000000..ffd883260c
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hypercall exception as hypercall requests.
+
Quoted 8 lines

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

Quoted 6 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +6 -0
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+Domains use 'hvc' instruction to invoke hypercalls.

Are you trying to describe any hypercalls (e.g. SMCCC, Xen...) or just the Xen one? If the latter, only "hvc #0xEA1" will be used for Xen hypercalls. Other immediate/space will be used for something different (i.e. #0 is used for SMCCC).

Yes, only the Xen one. I will mention "hvc #0xEA1".

Quoted 15 lines

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

Quoted 13 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +12 -0
+> +Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 to read the first parameter, x1 for second parameter and so
+on, for domain hypercall requests.

This implies we are supporting a large number of parameters. However, Xen is only support 5 arguments. So I would just list all the registers.

Quoted 3 lines

Xen shall use the first five cpu core registers to obtain the arguments for domain hypercall requests. Xen shall read the first register for the first argument, second register for the second argument and so on.

@Bertrand :- Does this look ok to you ? I deliberately changed from x0 to first register so that this can be valid for both arm64 and arm32. Please comment.

Yes we should mention the 5 registers as those are the one supported by Xen and also the register where the hypercall number is passed as mentioned after

Cheers
Bertrand

Quoted 146 lines
Quoted 13 lines

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

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

You don't seem to describe how the hypercall number is passed. Is this intended?

Good catch. I will add a requirement.

Xen shall read x16 to obtain the hypercall number.

Xen shall read r12 to obtain the hypercall number.

Quoted 82 lines
Quoted 82 lines
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +14 -0
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0 register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_ret_val~1`
docs/fusa/reqs/index.rst +2 -0
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 +26 -0
new file mode 100644
index 0000000000..03221f70c3
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Xen shall treat the first argument (as an integer) to denote the command number
+for the hypercall.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Second Parameter
+----------------
Quoted 8 lines

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

Quoted 6 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +6 -0
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the second argument as a virtual address to buffer in domain's
+memory.

We don't support any VA. The VA will need to be mapped with specifc attributes (see include/public/arch-arm.h). Should this be mentioned in the requirement?

....as a virtual address (mapped as Normal Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's ....

- Ayan

Quoted 31 lines
Quoted 31 lines
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +29 -0
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Return Value
+------------
+
+`XenProd~version_hyp_ret_val~1`
+
+Description:
+In case the hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
\ No newline at end of file