[xen staging] docs: fusa: Define the requirements for XEN_VERSION hypercall.

[patchbot@xxxxxxx]

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

    docs: fusa: Define the requirements for XEN_VERSION hypercall.
    
    Define the requirements which are common for all the commands.
    
    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    | 60 +++++++++++++++++++++++
 docs/fusa/reqs/index.rst                          |  2 +
 docs/fusa/reqs/market-reqs/reqs.rst               | 16 ++++++
 docs/fusa/reqs/product-reqs/version_hypercall.rst | 42 ++++++++++++++++
 4 files changed, 120 insertions(+)

diff --git a/docs/fusa/reqs/design-reqs/arm64/hypercall.rst 
b/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
new file mode 100644
index 0000000000..82ecf690a3
--- /dev/null
+++ b/docs/fusa/reqs/design-reqs/arm64/hypercall.rst
@@ -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`
diff --git a/docs/fusa/reqs/index.rst b/docs/fusa/reqs/index.rst
index 1088a51d52..d8683edce7 100644
--- a/docs/fusa/reqs/index.rst
+++ b/docs/fusa/reqs/index.rst
@@ -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
diff --git a/docs/fusa/reqs/market-reqs/reqs.rst 
b/docs/fusa/reqs/market-reqs/reqs.rst
index 2d297ecc13..7e3912c8f8 100644
--- a/docs/fusa/reqs/market-reqs/reqs.rst
+++ b/docs/fusa/reqs/market-reqs/reqs.rst
@@ -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
diff --git a/docs/fusa/reqs/product-reqs/version_hypercall.rst 
b/docs/fusa/reqs/product-reqs/version_hypercall.rst
new file mode 100644
index 0000000000..b824c539b0
--- /dev/null
+++ b/docs/fusa/reqs/product-reqs/version_hypercall.rst
@@ -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
--
generated by git-patchbot for /home/xen/git/xen.git#staging