Skip to contentSkip to conversation

docs: fusa: Define the requirements for XEN_VERSION hypercall.

PATCH In review Ayan Kumar Halder 2 participants 4 messages Aug 19, 2025 – Sep 22, 2025

lore
Share & tools
lore
#0 lore raw

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

Define the requirements which are common for all the commands.

---
Changes from -

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

v2 - 1. Specified the register details.
2. Specified the type of buffer.

v3 - Fixed some wordings to make it precise (eg register details, bit fields).

 .../fusa/reqs/design-reqs/arm64/hypercall.rst | 60 +++++++++++++++++++
 docs/fusa/reqs/index.rst                      |  2 +
 docs/fusa/reqs/market-reqs/reqs.rst           | 16 +++++
 .../reqs/product-reqs/version_hypercall.rst   | 42 +++++++++++++
 4 files changed, 120 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/hypercall.rst
 create mode 100644 docs/fusa/reqs/product-reqs/version_hypercall.rst
docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +60 -0
new file mode 100644
index 0000000000..82ecf690a3
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hvc instruction execution (with 0xEA1) as hypercall
+requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+The exception syndrome register should have the following values :-
+ESR_EL2.ISS should be 0xEA1.
+ESR_EL2.EC should be 0x16.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 - x4 core registers to obtain the arguments for domain hypercall
+requests.
+
+Rationale:
+
+Comments:
+Xen shall read x0 for the first argument, x1 for the second argument and so on.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Hypercall number
+----------------
+
+`XenSwdgn~arm64_hyp_num~1`
+
+Description:
+Xen shall read x16 to obtain the hypercall number.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
docs/fusa/reqs/index.rst +2 -0
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..7e3912c8f8 100644
@@ -79,3 +79,19 @@ Comments:
 
 Needs:
  - XenProd
+
+Version hypercall
+-----------------
+
+`XenMkt~version_hypercall~1`
+
+Description:
+Xen shall provide a hypercall for the domains to retrieve Xen's version, type
+and compilation information.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +42 -0

42 lines not on this page · raw message

Signature · 1 line
2.25.1
#1 lore raw

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

v2 - 1. Moved few changes to previous patch.

v3 - 1. Removed the internal implementation details from the design requirements so that they can be verified by black box tests.

 .../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++
 .../design-reqs/arm64/version_hypercall.rst   | 32 +++++++
 .../reqs/design-reqs/version_hypercall.rst    | 63 ++++++++++++++
 docs/fusa/reqs/index.rst                      |  3 +
 docs/fusa/reqs/product-reqs/hypercall.rst     | 20 +++++
 .../reqs/product-reqs/version_hypercall.rst   | 85 +++++++++++++++++++
 6 files changed, 218 insertions(+)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/design-reqs/version_hypercall.rst
 create mode 100644 docs/fusa/reqs/product-reqs/hypercall.rst
docs/fusa/reqs/design-reqs/arm64/hypercall.rst +15 -0
index 82ecf690a3..3b4af18323 100644
@@ -58,3 +58,18 @@ Comments:
 Covers:
  - `XenProd~version_hyp_first_param~1`
  - `XenProd~version_hyp_second_param~1`
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~hyp_err_ret_val~1`
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +32 -0
new file mode 100644
index 0000000000..ccfcb35a7a
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall return xen-3.0-aarch64 to denote that the cpu is running in arm64 mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
+Capabilities AArch32
+--------------------
+
+`XenSwdgn~arm64_capabilities_aarch32~1`
+
+Description:
+Xen shall return xen-3.0-armv7l to denote that the cpu is running in arm32 mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +63 -0

63 lines not on this page · raw message

docs/fusa/reqs/index.rst +3 -0
index d8683edce7..de19b0cda2 100644
@@ -11,6 +11,9 @@ Requirements documentation
    product-reqs/reqs
    product-reqs/arm64/reqs
    product-reqs/version_hypercall
+   product-reqs/hypercall
    design-reqs/arm64/generic-timer
    design-reqs/arm64/sbsa-uart
    design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/hypercall.rst new file +20 -0
new file mode 100644
index 0000000000..9fb46cf451
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Error Return Value
+------------------
+
+`XenProd~hyp_err_ret_val~1`
+
+Description:
+In case any hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
docs/fusa/reqs/product-reqs/version_hypercall.rst +85 -0

88 lines not on this page · raw message

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

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

Hi Ayan,

Quoted 6 lines · Ayan Kumar Halder

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

Looks good to me.

Cheers
Bertrand

Quoted 289 lines

---
Changes from -

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

v2 - 1. Moved few changes to previous patch.

v3 - 1. Removed the internal implementation details from the design requirements so that they can be verified by black box tests.

.../fusa/reqs/design-reqs/arm64/hypercall.rst | 15 ++++
.../design-reqs/arm64/version_hypercall.rst   | 32 +++++++
.../reqs/design-reqs/version_hypercall.rst    | 63 ++++++++++++++
docs/fusa/reqs/index.rst                      |  3 +
docs/fusa/reqs/product-reqs/hypercall.rst     | 20 +++++
.../reqs/product-reqs/version_hypercall.rst   | 85 +++++++++++++++++++
6 files changed, 218 insertions(+)

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst +0 -0
index 82ecf690a3..3b4af18323 100644
@@ -58,3 +58,18 @@ Comments:

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst +15 -0
+
+Return value
+------------
+
+`XenSwdgn~arm64_ret_val~1`
+
+Description:
+Xen shall store the return value in x0.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~hyp_err_ret_val~1`
docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst new file +32 -0
new file mode 100644
index 0000000000..ccfcb35a7a
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Capabilities
+------------
+
+`XenSwdgn~arm64_capabilities~1`
+
+Description:
+Xen shall return xen-3.0-aarch64 to denote that the cpu is running in arm64 mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
+Capabilities AArch32
+--------------------
+
+`XenSwdgn~arm64_capabilities_aarch32~1`
+
+Description:
+Xen shall return xen-3.0-armv7l to denote that the cpu is running in arm32 mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_capabilities_cmd~1`
+
docs/fusa/reqs/design-reqs/version_hypercall.rst new file +63 -0
new file mode 100644
index 0000000000..b05481b9dc
@@ -0,0 +1,63 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version
+-------
+
+`XenSwdgn~version~1`
+
+Description:
+Xen shall return its version when XENVER_version command is invoked.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_version_cmd~1`
+
+Error copying buffer
+--------------------
+
+`XenSwdgn~error_copy_buffer~1`
+
+Description:
+Xen shall return -EFAULT if it is not able to copy data to domain's buffer.
+
+Rationale:
+-EFAULT is one of the error code defined in
+http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.
+
+Comments:
+
+Covers:
+ - `XenProd~hyp_err_ret_val~1`
+
+Extraversion
+------------
+
+`XenSwdgn~extraversion~1`
+
+Description:
+Xen shall return its extraversion when XENVER_extraversion command is invoked.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_extraversion_cmd~1`
+
+Changeset
+---------
+
+`XenSwdgn~changeset~1`
+
+Description:
+Xen shall return its changeset when XENVER_changeset command is invoked.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_changeset_cmd~1`
docs/fusa/reqs/index.rst +3 -0
index d8683edce7..de19b0cda2 100644
@@ -11,6 +11,9 @@ Requirements documentation
   product-reqs/reqs
   product-reqs/arm64/reqs
   product-reqs/version_hypercall
+   product-reqs/hypercall
   design-reqs/arm64/generic-timer
   design-reqs/arm64/sbsa-uart
   design-reqs/arm64/hypercall
+   design-reqs/arm64/version_hypercall
+   design-reqs/version_hypercall
docs/fusa/reqs/product-reqs/hypercall.rst new file +20 -0
new file mode 100644
index 0000000000..9fb46cf451
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Error Return Value
+------------------
+
+`XenProd~hyp_err_ret_val~1`
+
+Description:
+In case any hypercall fails, Xen shall return one of the error codes defined
+in http://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/errno.h.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
docs/fusa/reqs/product-reqs/version_hypercall.rst +0 -0
index b824c539b0..466eb4108b 100644
@@ -40,3 +40,88 @@ Covers:
 

Needs:
- XenSwdgn

docs/fusa/reqs/product-reqs/version_hypercall.rst +85 -0
+
+Version command
+---------------
+
+`XenProd~version_hyp_version_cmd~1`
+
+Description:
+Xen shall provide a command (num 0) for  hypercall (num 17) to retrieve Xen's
+version in the domain's register 0.
+
+Rationale:
+
+Comments:
+Xen version is composed of major (ie version) and minor (ie subversion) number.
+The minor number is encoded in the 16 least significant bits and the major number
+is encoded in the top remaining bits.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Extraversion command
+--------------------
+
+`XenProd~version_hyp_extraversion_cmd~1`
+
+Description:
+Xen shall provide a command (num 1) for hypercall (num 17) to copy its
+extraversion in the domain's buffer.
+
+Rationale:
+
+Comments:
+Xen's extra version consists of a string passed with 'XEN_VENDORVERSION' command
+line parameter while building Xen.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Capabilities command
+--------------------
+
+`XenProd~version_hyp_capabilities_cmd~1`
+
+Description:
+Xen shall provide a command (num 3) for hypercall (num 17) to copy its
+capabilities to the domain's buffer.
+
+Rationale:
+
+Comments:
+Capabilities related information is represented by char[1024].
+For Arm64, the capabilities should contain "xen-3.0-aarch64" string.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Changeset command
+-----------------
+
+`XenProd~version_hyp_changeset_cmd~1`
+
+Description:
+Xen shall provide a command (num 4) for hypercall (num 17) to copy changeset
+to the domain's buffer.
+
+Rationale:
+
+Comments:
+Changeset is string denoting the date, time and git hash of the last change
+made to Xen's codebase.
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
Signature · 1 line
2.25.1
Reviewed-by on v4 1/2
#3 lore raw
In reply to Ayan Kumar Halder

Hi Ayan,

Quoted 5 lines · Ayan Kumar Halder

Define the requirements which are common for all the commands.

Looks good

Cheers
Bertrand

Quoted 174 lines

---
Changes from -

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

v2 - 1. Specified the register details.
2. Specified the type of buffer.

v3 - Fixed some wordings to make it precise (eg register details, bit fields).

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

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

docs/fusa/reqs/design-reqs/arm64/hypercall.rst new file +60 -0
new file mode 100644
index 0000000000..82ecf690a3
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall
+=========
+
+Instruction
+-----------
+
+`XenSwdgn~arm64_hyp_instr~1`
+
+Description:
+Xen shall treat domain hvc instruction execution (with 0xEA1) as hypercall
+requests.
+
+Rationale:
+
+Comments:
+Hypercall is one of the communication mechanism between Xen and domains.
+Domains use hypercalls for various requests to Xen.
+The exception syndrome register should have the following values :-
+ESR_EL2.ISS should be 0xEA1.
+ESR_EL2.EC should be 0x16.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Parameters
+----------
+
+`XenSwdgn~arm64_hyp_param~1`
+
+Description:
+Xen shall use x0 - x4 core registers to obtain the arguments for domain hypercall
+requests.
+
+Rationale:
+
+Comments:
+Xen shall read x0 for the first argument, x1 for the second argument and so on.
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
+
+Hypercall number
+----------------
+
+`XenSwdgn~arm64_hyp_num~1`
+
+Description:
+Xen shall read x16 to obtain the hypercall number.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hyp_first_param~1`
+ - `XenProd~version_hyp_second_param~1`
docs/fusa/reqs/index.rst +2 -0
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..7e3912c8f8 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 a hypercall for the domains to retrieve Xen's version, type
+and compilation information.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
docs/fusa/reqs/product-reqs/version_hypercall.rst new file +42 -0
new file mode 100644
index 0000000000..b824c539b0
@@ -0,0 +1,42 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Version hypercall
+=================
+
+First Parameter
+---------------
+
+`XenProd~version_hyp_first_param~1`
+
+Description:
+Xen shall treat the value stored in x0 as the command number for the hypercall.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
+
+Second Parameter
+----------------
+
+`XenProd~version_hyp_second_param~1`
+
+Description:
+Xen shall treat the value stored in x1 as a domain virtual address (mapped as
+Normal Inner Write-Back Outer Write-Back Inner-Shareable) to buffer in domain's
+memory.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~version_hypercall~1`
+
+Needs:
+ - XenSwdgn
Signature · 1 line
2.25.1