Hi Ayan, > On 19 Aug 2025, at 13:27, Ayan Kumar Halder <ayan.kumar.hal...@amd.com> wrote: > > We have written the requirements for some of the commands of the XEN_VERSION > hypercall. > > Signed-off-by: Ayan Kumar Halder <ayan.kumar.hal...@amd.com>
Looks good to me. Reviewed-by: Bertrand Marquis <bertrand.marq...@arm.com> 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 >
