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

[Bertrand Marquis <Bertrand.Marquis@xxxxxxx>]

Hi Ayan,

> On 19 Aug 2025, at 13:27, Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx> wrote:
> 
> 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>

Looks good to me.

Reviewed-by: Bertrand Marquis <bertrand.marquis@xxxxxxx>

Cheers
Bertrand

> ---
> 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
> 
> 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
> -- 
> 2.25.1
>