[xen staging] docs: fusa: Add the requirements for some of the commands of XEN_VERSION

[patchbot@xxxxxxx]

commit 3d3a690f174e527275436f09720f5e74b1232c7b
Author:     Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
AuthorDate: Tue Aug 19 12:27:09 2025 +0100
Commit:     Michal Orzel <michal.orzel@xxxxxxx>
CommitDate: Tue Sep 30 09:04:27 2025 +0200

    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.
    
    Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
    Reviewed-by: Bertrand Marquis <bertrand.marquis@xxxxxxx>
---
 docs/fusa/reqs/design-reqs/arm64/hypercall.rst     | 15 ++++
 .../reqs/design-reqs/arm64/version_hypercall.rst   | 32 ++++++++
 docs/fusa/reqs/design-reqs/version_hypercall.rst   | 63 ++++++++++++++++
 docs/fusa/reqs/index.rst                           |  3 +
 docs/fusa/reqs/product-reqs/hypercall.rst          | 20 +++++
 docs/fusa/reqs/product-reqs/version_hypercall.rst  | 85 ++++++++++++++++++++++
 6 files changed, 218 insertions(+)

diff --git a/docs/fusa/reqs/design-reqs/arm64/hypercall.rst 
b/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
index 82ecf690a3..3b4af18323 100644
--- a/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
+++ b/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
@@ -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`
diff --git a/docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst 
b/docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
new file mode 100644
index 0000000000..ccfcb35a7a
--- /dev/null
+++ b/docs/fusa/reqs/design-reqs/arm64/version_hypercall.rst
@@ -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`
+
diff --git a/docs/fusa/reqs/design-reqs/version_hypercall.rst 
b/docs/fusa/reqs/design-reqs/version_hypercall.rst
new file mode 100644
index 0000000000..b05481b9dc
--- /dev/null
+++ b/docs/fusa/reqs/design-reqs/version_hypercall.rst
@@ -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`
diff --git a/docs/fusa/reqs/index.rst b/docs/fusa/reqs/index.rst
index d8683edce7..de19b0cda2 100644
--- a/docs/fusa/reqs/index.rst
+++ b/docs/fusa/reqs/index.rst
@@ -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
diff --git a/docs/fusa/reqs/product-reqs/hypercall.rst 
b/docs/fusa/reqs/product-reqs/hypercall.rst
new file mode 100644
index 0000000000..9fb46cf451
--- /dev/null
+++ b/docs/fusa/reqs/product-reqs/hypercall.rst
@@ -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
diff --git a/docs/fusa/reqs/product-reqs/version_hypercall.rst 
b/docs/fusa/reqs/product-reqs/version_hypercall.rst
index b824c539b0..466eb4108b 100644
--- a/docs/fusa/reqs/product-reqs/version_hypercall.rst
+++ b/docs/fusa/reqs/product-reqs/version_hypercall.rst
@@ -40,3 +40,88 @@ 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
+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
--
generated by git-patchbot for /home/xen/git/xen.git#staging